PHP Manual

# PHP マニュアル

2026-06-20
PHP マニュアル翻訳プロジェクト

# 著作権

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

(訳注)このドキュメントは、オリジナル（英語）の日本語訳です。 本日本語訳の記述内容により生じたいかなる損害についても 著作権所有者および翻訳者は責任を負いません。

# PHP マニュアル

# このマニュアルについて

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

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

このマニュアルには、もっとも直近のメジャーバージョンふたつ分の PHP のリリースの情報(バージョン 7 と 8) が含まれています。 これらのバージョンに既に含まれていない拡張モジュールの情報と、 これらのバージョンより前の変更点は含まれていません。 これらのバージョンより前の PHP についてドキュメント化した、 古いマニュアルのアーカイブは » PHP のサイトの "Documentation" のページ に情報があります。

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

# 著者と貢献者

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

# 著者と編集者

以下の方々は本マニュアルに ついてコンテンツを提供したことで大きな貢献をしています。 Mehdi Achour, Bill Abt, Jouni Ahto, Alexander Aulbach, Stig Bakken, George Peter Banyard, Christoph M. Becker, Daniel Beckham, Friedhelm Betz, Nilgün Belma Bugüner, 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, Nuno Lopes, Hannes Magnusson, Stanislav Malyshev, Justin Martin, Rafael Martinez, Rick McGuire, Moacir de Oliveira Miranda Júnior, 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, Damien Seguy, Masahiro Takagi, Yoshinari Takaoka, Yannick Torres, Jakub Vrana, Michael Wallner, Lars Torben Wilson, Jim Winstead, Jeroen van Wolffelaar そして Andrei Zmievski.

以下の方々は本マニュアルについて多くの編集作業を行ったことで大きな貢献を しています。 Stig Bakken, Peter Cowburn, 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: 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を使用した開発ではサーバーサイドでの動作に焦点が当てられますが、 他にも多くのことが可能です。 PHPにできることは?まで読み進めてみてください。 Webプログラミングのみに関心がある場合には、 簡易チュートリアルに進んでください。

## PHPにできることは?

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

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

- サーバーサイドでのスクリプティング。これは幅広く使われていて PHPの中心となる分野です。ここでPHPを動作させるには 3つのものが必要です。PHPパーサー(CGIもしくはサーバーモジュール)、 ウェブサーバー、そしてブラウザです。これらはいずれもローカルマシンで 実行して PHP プログラミングを試すことができます。 インストール手順の章に詳しい 情報があります。
- コマンドラインでのスクリプティング。PHPスクリプトは サーバーもブラウザも無しで動作させるようにすることも出来ます。 この場合、PHPパーサーだけが必要となります。このタイプは cron(Unix および macOS) やタスクスケジューラ(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 はインストール済みであることを想定しています。 インストール方法については、 » ダウンロードページ を参照ください。

以下の内容で hello.php という名前のファイルを作成してください:

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

    <?php

    echo "Hello World!";

    ?>

ターミナルを使い、このファイルがあるディレクトリに移動し、 以下のコマンドで開発用のサーバーを起動します:

    php -S localhost:8000

ブラウザを使用して、`/hello.php` で終わる Web アクセス用 URL を指定し、 このファイルにアクセスしてください。 先程のコマンドを実行済みの場合、この URL は `http://localhost:8000/hello.php` のようになります。 全てが正しく設定されている場合、 このファイルは PHP によりパースされ、 "Hello World" がブラウザで表示されます。

PHP は通常のHTMLの Webページにも埋め込むことができます。 つまり、HTML ドキュメントを PHP の文を使って書けるということです。 そのことを示すデモが以下になります:

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

上記の出力は、以下のようになります:

    <!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 モードを抜けて 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>
        <p>あなたはFirefoxを使用しています</p>
        <?php
    } else {
        ?>
        <h3>str_contains()がfalseを返しました</h3>
        <p>あなたはFirefoxを使用していません</p>
        <?php
    }
    ?>

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

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

何かを出力する際に 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 データの混ざったものが含まれます。

## 次にするべきことは?

ここで得た知識により、マニュアルのほとんどの部分を理解できるようになったはずです。

特に、以下の機能を調べてみるとよいでしょう:

- ファイルシステム関数を使ってファイルを読み書きする
- ファイルのアップロードを処理する
- Curl を使ってリモートのページやファイルを取得する
- PDO を使ってデータベースにデータを保存し、分析する (SQLite はデータベースサーバーを動かさなくても使えます)
- セッションを使ってリクエストをまたいでデータを保持する

あらゆる場面に対応する膨大なライブラリや» フレームワークが、 » Packagist リポジトリにそろっており、 いずれも Composer パッケージマネージャを使ってインストールできます。

コミュニティによる手助けやアドバイスについては、» ヘルプページを確認してください。

さまざまなポッドキャストやプレゼンテーション、その他の動画については、 » コミュニティの PeerTube を確認してください。

役に立つその他のコミュニティのリソースとしては、「awesome リスト」 (厳選されたリンク集) や 「開発者ロードマップ」 (関連トピックの一覧) などがあります。

どこから手をつければよいか見当もつかず行き詰まったときは、 プロジェクトや問題をより小さな部分に分解してみましょう。 そうすれば、自分がすでにできることと、これから学ぶ必要があることを見極めやすくなります。 この分解は必要なだけ深く / 詳細にして構いません。 たとえば、ブログを作る場合は以下のような部分に分解できるでしょう:

- ページの一覧表示と閲覧
  - データベースからレコード (ページ) を読み込む
- ページの作成
  - フォームの送信を処理する
  - データベースにレコード (ページ) を書き込む
- 管理者ログイン
  - データベースからレコード (ユーザー) を読み込む
  - パスワードを扱う
  - リクエストやページをまたいでデータ (ユーザーのログイン) を保持する (セッション)

特に作りたいものがない場合は、kata やチャレンジ、「コードゴルフ」といったコーディング演習を探してみるのもよいでしょう。 PHP に特化したものでなくても、ほとんどは解くことができ、知識と思考力を試すよい挑戦になるはずです。

- 入門 — PHP は何ができるものですか?
- 簡易チュートリアル
  - PHP を使用する初めてのページ
  - 実用的な例
  - フォームの処理
  - 次にするべきことは?

# インストールと設定

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

インストールを行う前に、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 システムへのインストール

## 目次

- Debian GNU/Linux および関連ディストリビューションのパッケージからのインストール
- DNF を使用する GNU/Linux ディストリビューションでのパッケージからのインストール
- OpenBSD パッケージまたは ports からのインストール
- Unix および macOS システムでのソースコードからのインストール
- CGI およびコマンドライン
- Apache 2.x (Unixシステム用)
- Nginx 1.4.x (Unix システム用)
- Lighttpd 1.4 (Unix システム用)
- LiteSpeed/OpenLiteSpeed Webサーバー(Unixシステム用)
- Solaris へのインストール

ほとんどの Unix (および Linux) オペレーティングシステムとディストリビューションには、 パッケージシステムを通じて利用できるパッケージされたバージョンの PHP と拡張モジュールがあります。 これらのシステムを使用して PHP をインストールするための基本情報を記載したセクションがあります。

一部のディストリビューションには、バージョンや拡張モジュールなどの幅広い選択肢があるパッケージを 提供しているサードパーティのリポジトリもあります。

PHP は、一部のアプリケーションサーバーのコンポーネントとしてインストールすることもできます。

最後に、PHP は常にソースコードからインストールできます。 これによって、どの機能や拡張モジュール、SAPI を有効にするかについて、 最も大きな柔軟性を得ることができます。 異なる SAPI を使って PHP を設定し、コンパイルすることに関するセクションもあります。

## Debian GNU/Linux および関連ディストリビューションのパッケージからのインストール

PHP はソースコードからもインストールできますが、 » Debian GNU/Linux パッケージからもインストール可能です。これは、Ubuntu、Kali Linux、Linux Mint のような Debian ベースの他のディストリビューションにも当てはまります。

警告

サードパーティによるビルドは非公式であり、PHP プロジェクトによって 直接サポートされません。発生したバグは、 » 公式ダウンロードページ からのビルドで再現できなければ、非公式ビルドの提供元に報告してください。

パッケージは、 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` などの基本的な PHP コンポーネントと多くの PHP 拡張モジュールを含む多数のパッケージが含まれます。 拡張モジュールがインストールされると、それらのパッケージの依存関係を満たすために、 必要に応じて追加のパッケージが自動的にインストールされます。

例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 ファイルが読み込まれているかどうかと インストール後にウェブサーバーを再起動したかどうかを確認しましょう。

## DNF を使用する GNU/Linux ディストリビューションでのパッケージからのインストール

PHP はソースコードからインストールできますが、Red Hat Enterprise Linux、 OpenSUSE、Fedora、CentOS、Rocky Linux、Oracle Enterprise Linux のような DNF を使用するシステム上のパッケージからインストールすることもできます。

警告

サードパーティによるビルドは非公式であり、PHP プロジェクトによって 直接サポートされません。発生したバグは、 » 公式ダウンロードページ からのビルドで再現できなければ、非公式ビルドの提供元に報告してください。

パッケージは dnf コマンドでインストールできます。

### Installing packages

まず、» PEAR には `php-pear`、 MySQL 拡張 には `php-mysqlnd` など、 他の関連パッケージが必要になる場合があることに気をつけてください。

次に、パッケージをインストールする前に、パッケージリストが最新であることを確認するのが賢明です。 通常、これは dnf update コマンドを実行して行います。

例1 DNF インストールの例

    # dnf install php php-common

DNF は Web サーバー に自動的に PHP のための設定をインストールしますが、 変更を有効化するには、以下のようなコマンドでサーバーの再起動が必要になる場合があります。

例2 Restarting Apache once PHP is installed

    # sudo systemctl restart httpd

### 設定のよりよい管理方法

これまでのセクションでは、PHP はコアモジュールのみをインストールしました。 次のような追加モジュールが必要になる可能性が非常に高くなります。 MySQL, cURL, GD, などなど… これらのモジュールも dnf コマンドでインストールできます。

例3 追加の PHP パッケージを一覧する方法

    # dnf search php

パッケージのリストには、`php-cli`、`php-fpm`、 `php-devel` などの基本的な PHP コンポーネントや、多くの PHP 拡張モジュールを含む数多くのパッケージが含まれています。拡張モジュールがインストールされると、 それらのパッケージの依存関係を満たすために、 必要に応じて追加のパッケージが自動的にインストールされます。

例4 Install PHP with MySQL, GD

    # dnf install php-mysqlnd php-gd

DNF は、/etc/php/8.3/php.ini、/etc/php/8.3/conf.d/*.ini などのさまざまな php.ini 関連ファイルに適切な行を自動的に追加し、 拡張モジュールに応じて `extension=foo.so` のようなエントリを追加します。 ただし、これらの変更の有効化するには、Web サーバー (Apache など) を再起動しなければなりません。

## OpenBSD パッケージまたは ports からのインストール

このセクションでは、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 を参照ください) で追加できます。

## Unix および macOS システムでのソースコードからのインストール

コンパイルに必要なソフトウェア:

- » GNU make
- C コンパイラ (PHP 8.0.0 以降は C99、PHP 8.4.0 以降は C11 互換性が必須)
- Web サーバー
- モジュールごとに必要なコンポーネント (GD、 PDF ライブラリなど)

Git ソースから直接ビルドする場合や、PHP のソースコードをカスタムしてビルドする場合、 以下の追加ツールが必要になる場合があります。

- » autoconf:
  - PHP 7.3 以降: バージョン 2.68 以上
  - PHP 7.2: バージョン 2.64 以上
  - PHP 7.1 以前: バージョン 2.59 以上
- » 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+ 以上 (3.x を含む)

PHP をソースコードからコンパイルする、さらに詳細なステップについては、 ソースの tar ボールに入っている » README.md を参照ください。

PHP の初期セットアップと構成プロセスは、configure スクリプトのコマンドライン オプションを使用して制御されます。 ./configure --help を実行すると、 使用可能なオプションの一覧と簡単な説明が表示されます。 このマニュアルでは、さまざまなオプションを個別に説明しています。 中心となる configure オプションのリストはこちら にありますが、さまざまな拡張モジュールごとに固有のオプションについては リファレンスページで説明されています。

構成スクリプトが実行された後、make コマンドを使用して PHP をビルドできます。マニュアルのインストールについてのよくある質問 のページには、ビルドの問題の対処方法についての詳細情報があります。

> 注意: 一部の Unix システム (OpenBSD や SELinux など) では、 » PaX MPROTECT または » W^X violation protection と呼ばれるセキュリティ上の理由から、書き込み可能ページ と実行可能ページの両方のマッピングを禁止する場合があります。この種のメモリ マッピングは PCRE の JIT サポートに必要であるため、PHP を PCRE の JIT サポートなし でビルドするか、システムが提供する何らかの手段でバイナリを ホワイトリストに登録する必要があります。

> 注意: いまのところ、Android ツールチェーンを使用した ARM のクロスコンパイルはサポートされていません。

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

## 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` ファイルを編集します。 php.ini ファイルを他の場所に置きたい場合は、手順 5 で、 オプション `--with-config-file-path=/some/path` を使用します。

   php.ini-developmentent ではなく、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` を使うと、`.php` ファイルに名前を変えたりコピーしたりしなくても 任意の `.phps` ファイルを構文ハイライトつきのソースコードとして表示させることができます。

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

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

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

       /usr/local/apache2/bin/apachectl start

   または、以下の手順でも起動できます。

       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 を参照ください。

## 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 コマンドを使ったインストールに必要なコンポーネントの大半が含まれています。

# macOS へのインストール

## 目次

- サードパーティパッケージによる macOS へのインストール
- macOS 上での PHP のコンパイル
- macOS Monterey より前のバージョンにバンドルされている、PHP の使用法

PHP は macOS バージョン10 および 11 に標準添付されていましたが、 macOS Monterey (12.0.0) 以降には含まれていません。 最近のバージョンにインストールするには、サードパーティーのパッケージを使用するか、 ソースコードからコンパイルする必要があります。

## サードパーティパッケージによる macOS へのインストール

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

macOS に PHP をインストールするには、 » Homebrew パッケージマネージャを使用すると簡単です。

1. Web サイトの指示に従って Homebrew をインストールしてください。

2. brew install php

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

- » MacPorts
- » Fink

## macOS 上での PHP のコンパイル

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

## 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() をコールしても、この情報を取得できます。

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

## 目次

- Windows でのおすすめの構成
- ビルド済みバイナリの手動インストール
- Apache 2.x （Microsoft Windows 用）
- Windows の IIS と一緒にインストール
- PHP をインストールするためのサードパーティーツール
- ソースからのビルド
- Windows で PHP をコマンドラインで動かす

Windows 版の PHP の公式リリースは、実運用環境でも使えるものです。 しかし、PHP を ソースコードからビルド することもできます。

PHP は Azure App Services (aka Microsoft Azure, Windows Azure, (Windows) Azure Web Apps) 上でもインストールできます。

インストールに関する FAQ のページは、発生する可能性のある一般的なインストール上の問題や、 設定の問題を扱っています。

## Windows でのおすすめの構成

### OpCache

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

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

例1 OpCache の推奨構成

    opcache.enable=On
    opcache.enable_cli=On

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

### WinCache

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

## ビルド済みバイナリの手動インストール

### インストールに必要なもの

PHP は 32bit x86 または 64bit x64 システムでだけ利用できます。 そして、現状では ARM で動作する Windows RT では利用できません。 PHP 8.3.0 以降では、Windows 8 または Windows Server 2012 が必要です。 PHP 7.2.0 以降では、Windows 7 または Windows Server 2008 R2 が必要です。 PHP 7.2.0 より前のバージョンでは、Windows 2008 や Vista がサポートしていました。

PHP は Visual C runtime(CRT) を必要とします。 他の多くのアプリケーションも CRT を必要としているので、 CRT は既にインストールされていそうではあります。 しかし、仮にインストールされていない場合は Microsoft Visual C++ Redistributable for Visual Studio 2022 が全ての PHP バージョンに適合しており、 » Microsoft のページ からダウンロードできます。

x86 版の PHP をビルドするには、x86 版の CRT が必要ですし、 x64 版の PHP をビルドするには、x64 版の CRT が必要です。 CRT が既にインストールされている場合は、 インストーラーは「既にインストールされている」旨を表示し、 システムを何も変更しません。 CRT のインストーラーは /quiet と /norestart コマンドラインオプションをサポートしているので、 インストール自体はスクリプトで自動化できます。

### どこから PHP バイナリをダウンロードするか

Windows 向けのビルドは » PHP Windows website からダウンロードできます。 全てのバイナリは最適化(PGO)されており、 QA が通されています。 そして、GA リリースは十分にテストされています。

### ビルド済みのPECL拡張モジュール

Windows 版のビルド済みPECL拡張モジュールは、 拡張モジュールのPECLページで DLL として配布されています。

Unix のような、Windows 以外のシステムに特有の機能を使っていたり、 Windows で利用できないライブラリに依存していたりする拡張モジュールは、 Windows でバイナリは利用できません。

### Build types

PHP のビルドには以下の4種類があります:

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

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

- x86 - 32-bit システム向け

- x64 - 64-bit システム向け

## 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 ハンドラとしてインストール

> 注意: apache2handler SAPI を使う場合は、Thread Safe (TS) 版の PHP を使わなければいけません。

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 の IIS と一緒にインストール

### IIS のインストール

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

> 注意: IIS と一緒に FastCGI ハンドラを使えば、 Non-Thread Safe (NTS) 版の PHP のビルドがインストールされるはずです。

### IIS と PHP を設定する

IIS マネージャー内で、FastCGI モジュールをインストールし、 `.php` のハンドラマッピングを php-cgi.exe に対して追加します。 (php.exe ではありません)

IIS の設定をスクリプト化するには、 APPCMD コマンドラインツールが使えます。

### サンプルのバッチスクリプト

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

    @echo off

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

    REM path to directory into which PHP .ZIP file was decompressed (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']"

## PHP をインストールするためのサードパーティーツール

警告

サードパーティによるビルドは非公式であり、PHP プロジェクトによって 直接サポートされません。発生したバグは、 » 公式ダウンロードページ からのビルドで再現できなければ、非公式ビルドの提供元に報告してください。

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

## ソースからのビルド

Visual Studio を使ってビルドするには、 » step-by-step build instructions を参照ください。

## 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 のフォーラムへの投稿 に説明があります。

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

## 目次

- 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 や拡張モジュールが動くということです。 しかし、Azure App Services の管理インターフェイスは、 Windows サーバーとは少し異なります。

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

- Kudu Dashboard: `site_name.azurewebsites.net` の Kudu dashboard は `https://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 への絶対パスを設定します。

## 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 が利用するイベントメカニズム。 epoll、kqueue (*BSD)、port (Solaris)、poll、select が利用可能です。 デフォルト値: 未設定 (自動検出。epoll または kqueue が優先的に使用されます)

`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` を参照。 グループ名を、カンマ区切りのリスト形式で指定します。

`listen.setfib` int

  associated the route table (FIB) を設定します。 FreeBSD でのみ有効です。 デフォルト: `-1`。 PHP 8.2.0 以降で利用可能です。

`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` または `ondemand` の場合は作成される子プロセスの最大数。 このオプションは必須です。

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

`pm.start_servers` int

  起動時に作成される子プロセスの数。`pm` が `dynamic` の場合にのみ使います。デフォルト値: (min_spare_servers + max_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` の値が `ondemand` である場合にのみ使えます。 使用可能な単位: 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。 以下のフォーマットが使えます: `%{user}C` user CPU のみ。 `%{system}C` system CPU のみ。 `%{total}C` user + system CPU (デフォルト)
  `%d` | リクエストの処理に掛かる時間。 精度について、以下のフォーマットが許可されています: `%{seconds}d` (デフォルト), `%{milliseconds}d`, `%{microseconds}d`.
  `%e` | 環境変数 ($_ENV や $_SERVER と同じ)。 変数の名前は、指定する環境変数の名前を中括弧で囲んだものでなければなりません。 たとえば、サーバーの変数として `%{REQUEST_METHOD}e` や `%{SERVER_PROTOCOL}e`、 HTTP ヘッダの変数として `%{HTTP_HOST}e` や `%{HTTP_USER_AGENT}e` が挙げられます。
  `%f` | script のファイル名
  `%l` | リクエストの `Content-Length` (HTTP POST のみ)
  `%m` | HTTP リクエストの method
  `%M` | PHP によって確保されたメモリのピーク値。 以下のフォーマットが使えます: `%{bytes}M` (デフォルト), `%{kilobytes}M`, `%{kilo}M`, `%{megabytes}M`, `%{mega}M`
  `%n` | Pool name
  `%{name}o` | 出力ヘッダ。 ヘッダ名は、中括弧で囲んで指定しなければいけません。 例: `%{Content-Type}o`, `%{X-Powered-By}o`, `%{Transfer-Encoding}o`
  `%p` | リクエストを処理した子プロセスの PID
  `%P` | リクエストを処理した子の親のPID
  `%q` | query string
  `%Q` | `'?'` 文字、または クエリストリングが存在した場合、 `%q` と `%r`, の間の glue
  `%r` | クエリストリングを除いたリクエストURI。 `%q` と `%Q` も参照ください。
  `%R` | remote IP address
  `%s` | Status (response code)
  `%t` | リクエストを受け取ったサーバー側の時刻。 `strftime(3)` のフォーマットを指定でき、デフォルトは `%d/%b/%Y:%H:%M:%S %z` です。 `strftime(3)` のフォーマットは `%{<strftime_format>}t` タグで囲む必要があります。 例えば、ISO8601 形式でフォーマットするには `%{%Y-%m-%dT%H:%M:%S%z}t` を使ってください。
  `%T` | ログが書き込まれた時間 (リクエストが終了した時間)。 `strftime(3)` のフォーマットを指定でき、デフォルトは `%d/%b/%Y:%H:%M:%S %z` です。 `strftime(3)` のフォーマットは `%{<strftime_format>}T` タグで囲む必要があります。 例えば、ISO8601 形式でフォーマットするには `%{%Y-%m-%dT%H:%M:%S%z}T` を使ってください。
  `%u` | `Authorization` ヘッダーで Basic 認証が指定されていれば、そのユーザー名

`access.suppress_path` array

  アクセスログからフィルタすべき request_uri のリスト。 デフォルト: 未設定。 PHP 8.2.0 以降で利用可能です。

追加の環境変数を渡して、特定のプールだけで 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 は別で、 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 インストール入門

> 注意: PHP Installer for Extensions (PIE) は、PECL を非推奨にする新しいツールです。 拡張モジュールをインストールする用途には、PIE を推奨します。 詳しい情報は、 » https://github.com/php/pie を参照ください。

» 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 拡張モジュールをダウンロードする

> 注意: PHP Installer for Extensions (PIE) は、PECL を非推奨にする新しいツールです。 拡張モジュールをインストールする用途には、PIE を推奨します。 詳しい情報は、 » https://github.com/php/pie を参照ください。

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

# Composer とサードパーティパッケージのインストール

## Composer 入門

» Composer は PHP 用の依存管理ツールで、プロジェクトで利用するサードパーティのパッケージを定義し、 そのインストールと更新が簡単に行えるようになります。 Composer は PHP 組み込みの クラスのオートロード機能 と、 » Packagist のような PHP パッケージのリポジトリ、そして共通のプロジェクト構造とコーディング規約を利用しています。

例えば、PHP アプリケーションやウェブサイトで UUID を利用する必要がある場合、» RFC 4122 で定義された、広く知られていて使われている UUID の形式を実装した » Ben Ramsey の `ramsey/uuid` パッケージ を利用することができます。

簡単に言うと、`composer.json` をプロジェクトに作成し、Composer を使って最新バージョンのパッケージをインストールし、 Composer のオートロードスクリプトを読み込むことでパッケージがコード内で利用可能となります。 詳細は » Composer の "Basic Usage" ドキュメント を参照してください。

例1 一つのパッケージを依存に持つ `composer.json`

    {
        "require": {
            "ramsey/uuid": "^4.7"
        }
    }

# PIE と サードパーティ拡張モジュールのインストール

## PIE の紹介

» PIE は PHP のためのインストーラーです。 これを使うと、サードパーティの PHP 拡張モジュールをインストールできます。 しかもインストールや更新が簡単にできます。 PIE は PHP 拡張モジュールのリポジトリとして、 » Packagist を利用しており、 それを用いてソースコードを探し、拡張機能をビルドしています。 さらに存在する場合には、 Packagist 経由で Windows バイナリもダウンロードします。 ソースコードをダウンロードした場合、 そのビルドの仕方やインストール方法も PIE は把握しています。

» PIE とその動作に必要なものをインストール した後は、 コマンドラインから以下を実行することで、 MongoDB 拡張モジュール をインストールできます。

例1 MongoDB 拡張モジュール を PIE を使ってインストールする

    pie install mongodb/mongodb-extension

さらに詳しいことは、 » "PIE Usage" documentation が説明しています。

# 実行時設定

## 目次

- 設定ファイル
- .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 の中で環境変数を参照するには、次のようにします。 PHP 8.3.0 以降では、参照する変数が未定義の場合にフォールバックする値を 指定できるようになりました。

例1 php.ini での環境変数

    ; 環境変数 PHP_MEMORY_LIMIT を利用します
    memory_limit = ${PHP_MEMORY_LIMIT}
    ; 環境変数 PHP_MAX_EXECUTION_TIME が未定義の場合、30 にフォールバックします
    max_execution_time = ${PHP_MAX_EXECUTION_TIME:-30}

拡張モジュールに対する 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 レジストリ を使って) で設定できます。 .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() 関数を用いて、個々のオプションの設定値にアクセスすることも可能です。

- インストールにあたっての一般的な注意事項
- Unix システムへのインストール
  - Debian GNU/Linux および関連ディストリビューションのパッケージからのインストール
  - DNF を使用する GNU/Linux ディストリビューションでのパッケージからのインストール
  - OpenBSD パッケージまたは ports からのインストール
  - Unix および macOS システムでのソースコードからのインストール
  - CGI およびコマンドライン
  - Apache 2.x (Unixシステム用)
  - Nginx 1.4.x (Unix システム用)
  - Lighttpd 1.4 (Unix システム用)
  - LiteSpeed/OpenLiteSpeed Webサーバー(Unixシステム用)
  - Solaris へのインストール
- macOS へのインストール
  - サードパーティパッケージによる macOS へのインストール
  - macOS 上での PHP のコンパイル
  - macOS Monterey より前のバージョンにバンドルされている、PHP の使用法
- Windows システムへのインストール
  - Windows でのおすすめの構成
  - ビルド済みバイナリの手動インストール
  - Apache 2.x （Microsoft Windows 用）
  - Windows の IIS と一緒にインストール
  - PHP をインストールするためのサードパーティーツール
  - ソースからのビルド
  - 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 に静的に組み込む
- Composer 入門
- PIE の紹介
- 実行時設定
  - 設定ファイル
  - .user.ini ファイル
  - どこで設定を行うのか
  - 設定を変更するには

# 言語リファレンス

# 基本的な構文

## 目次

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

## PHP タグ

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 が出力バッファリングを開始し、その時点の内容を意図せず出力してしまうことになります。

例2 PHP コードのみのファイル

    <?php
    echo "みなさん、こんにちは\n";

    // ... いろんなコードたち

    echo "最後のごあいさつ\n";

    // PHP 終了タグを書かずに、ここでスクリプトを終わります。

## HTML からの脱出

PHP のパーサーは、開始タグと終了タグに囲まれていない部分をすべて無視します。 そのおかげで、PHP のファイルにそれ以外のコンテンツを混在させることができるのです。 たとえば PHP を HTML ドキュメントに組み込んで、テンプレートを作ったりすることもできます。

例1 HTML に PHP を埋め込む

    <p>この部分は PHP から無視され、そのままブラウザには表示されます。</p>
    <?php echo '一方、この部分はパースされます。'; ?>
    <p>この部分も PHP から無視され、そのままブラウザには表示されます。</p>

これは期待通りに動作します。なぜなら、PHP インタプリタは ?> 終了タグを見つけると それ以降新たに開始タグを見つけるまでの内容を何でも出力するからです (終了タグの直後の改行は別です。 命令の分離 を参照ください)。 しかし、PHP が条件文の中にいる場合は話が別です。 その場合は、まず条件式の結果を判定してから何をスキップするかを判断します。 次の例を参照ください。

条件文を使った例です。

例2 条件文を使った高度な脱出

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

例2 PHP パーサーの開始と終了の例

    <?php
        echo "テストです\n";
    ?>

    <?php echo "テストです\n" ?>

    <?php echo "終了タグを省略しました\n";

> 注意:

> ファイル終端における PHP ブロックの終了タグはオプション（任意）です。 include や require を利用する際には、 終了タグを省略する方が無難です。というのは、そうすることでファイルの最後に 予期せぬ空白文字があらわれてしまうことを防げますし、後でレスポンスに ヘッダを付加することも可能となるからです。また、出力バッファリングを 使用しており、include したファイルの生成する部分の最後に余計な空白を つけたくない場合などにも便利です。

## コメント

PHP は、'C', 'C++' および Unix シェル型（Perl 型）のコメントをサポートします。 例えば、

例1 コメント

    <?php
    echo "テストです\n"; // C++型の単一行用のコメント
    /* 複数行用のコメント
       もう一行分のコメント */
    echo "もうひとつのテストです\n";
    echo "最後のテストです\n"; # シェル型の単一行用のコメント
    ?>

"一行"コメントは、改行または PHP コードのブロックの終わり のうちどちらか最初にくる方までです。 つまり、`// ... ?>` あるいは `# ... ?>` の後に続く HTML コードは 表示されるということです。?> により PHP モードを終了して HTML モードに戻ると、そこでは `//` あるいは `#` は何の影響も 及ぼしません。

例2 一行コメント

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

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

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

# 型

## 目次

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

## はじめに

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

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

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

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

ヒント

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

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

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

例1 異なる型

    <?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)をサポートしており、 それらを組み合わせてより複雑な型を作ることができます。 そうした複雑な型の一部については、 型宣言 時に記述できます。

### 基本型

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

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

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

#### スカラー型

値が int, float, string, bool のうちのひとつの場合、スカラーとみなされます。

#### ユーザー定義型

インターフェイス, クラス, 列挙型(Enum) を使うと、カスタムの型を定義することができます。 これらはユーザー定義型、またはクラス型と見なせます。 たとえば、`Elephant` というクラスを定義することができます。 さらに、`Elephant` 型のオブジェクトをインスタンス化できます。 そして、関数は `Elephant` 型のパラメータをリクエストできます。

### 複合型

複数の基本型を組み合わせて、複合型を作ることができます。 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 のユニット型(意味のある情報を持たないことを示す型) です。 つまり、単一の値 `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に代入する

    var_dump($foo); // bool(true)
    ?>

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

    <?php

    $action = "show_version";
    $show_separators = true;

    // == は、等価性をテストして 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"`
- 要素の数がゼロである 配列
- ユニット型 NULL (値がセットされていない変数を含む)
- bool 型へキャストするように動作がオーバーロードされた内部オブジェクト。 例: 値 `0` を表す GMP オブジェクト。

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

警告

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

例1 Boolean にキャストする

    <?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 整数のオーバーフロー

    <?php
    $large_number = 50000000000000000000;
    var_dump($large_number);         // float(5.0E+19)

    var_dump(PHP_INT_MAX + 1);       // 32-bit system: float(2147483648)
                                     // 64-bit system: float(9.2233720368548E+18)
    ?>

### 整数の除算

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

例3 除算の例

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

### 整数への変換

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

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

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

#### booleans から

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

#### 浮動小数点数から

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

例4 float 型からキャストする

    <?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`, `Inf`, `-Inf` を 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 桁では等しくなります。

例1 浮動小数点数の比較

    <?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` といったおなじみのエスケープシーケンスを書いても特別な効果は得られず、 書いたままの形式で出力されます。

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

例1 Syntax Variants

    <?php
    echo 'this is a simple string', PHP_EOL;

    echo 'You can also have embedded newlines in
    strings this way as it is
    okay to do', PHP_EOL;

    // 出力: Arnold once said: "I'll be back"
    echo 'Arnold once said: "I\'ll be back"', PHP_EOL;

    // 出力: You deleted C:\*.*?
    echo 'You deleted C:\\*.*?', PHP_EOL;

    // 出力: You deleted C:\*.*?
    echo 'You deleted C:\*.*?', PHP_EOL;

    // 出力: This will not expand: \n a newline
    echo 'This will not expand: \n a newline', PHP_EOL;

    // 出力: Variables do not $expand $either
    echo 'Variables do not $expand $either', PHP_EOL;
    ?>

#### 二重引用符

文字列が二重引用符 (`"`) で括られた場合、 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 の他のラベルと同様の命名規則に従う必要があります。 つまり、英数字およびアンダースコアのみを含み、 数字でない文字またはアンダースコアで始まる必要があります。

例2 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 がスローされます。

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

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

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

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

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

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

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

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

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

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

例5 終端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 が起きる可能性があります。

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

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

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

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

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

警告

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

#### Nowdoc

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

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

例13 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 \'.

例14 変数がある場合の、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

例15 静的なデータの例

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

#### 文字列の補間処理

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

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

##### 単純な構文

ドル記号 (`$`) を見付けると、 その後に変数名で使える文字は変数として解釈され、置き換えられます。

例16 文字列の置き換え

    <?php
    $juice = "apple";

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

    ?>

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

    He drank some apple juice.

形式的には、文字列の変数の置き換えの文法は下記のようになります:

    string-variable::
         variable-name   (offset-or-property)?
       | ${   expression   }

    offset-or-property::
         offset-in-string
       | property-in-string

    offset-in-string::
         [   name   ]
       | [   variable-name   ]
       | [   integer-literal   ]

    property-in-string::
         ->  name

    variable-name::
         $   name

    name::
         [a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*

警告

`${ expression }` の形式は、 PHP 8.2.0 以降では推奨されなくなりました。 なぜなら、これは 可変変数: として解釈される可能性があるからです。

    <?php
    const foo = 'bar';
    $foo = 'foo';
    $bar = 'bar';
    var_dump("${foo}");
    var_dump("${(foo)}");
    ?>

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

    Deprecated: Using ${var} in strings is deprecated, use {$var} instead in file on line 6

    Deprecated: Using ${expr} (variable variables) in strings is deprecated, use {${expr}} instead in file on line 9
    string(3) "foo"
    string(3) "bar"

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

    string(3) "foo"
    string(3) "bar"

高度な 文字列補間の記法を代わりに使うべきです。

> 注意: 有効な変数名にならない場合、ドル記号は文字列中でそのまま解釈されます:

>     <?php
>     echo "No interpolation $  has happened\n";
>     echo "No interpolation $\n has happened\n";
>     echo "No interpolation $2 has happened\n";
>     ?>

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

>     No interpolation $  has happened
>     No interpolation $
>      has happened
>     No interpolation $2 has happened

例17 配列の最初の次元やプロパティの値を補間させる

    <?php
    $juices = array("apple", "orange", "string_key" => "purple");

    echo "He drank some $juices[0] juice.";
    echo PHP_EOL;
    echo "He drank some $juices[1] juice.";
    echo PHP_EOL;
    echo "He drank some $juices[string_key] juice.";
    echo PHP_EOL;

    class A {
        public $s = "string";
    }

    $o = new A();

    echo "Object value: $o->s.";
    ?>

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

    He drank some apple juice.
    He drank some orange juice.
    He drank some purple juice.
    Object value: string.

> 注意: 配列のキーについては、クォートを外さなければなりません。 よって、単純な記法では定数をキーとして参照できません。 高度な 記法を使ってください。

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

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

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

さらに複雑な処理は、 高度な 記法を使う必要があります。

##### 高度な (波括弧) 記法

高度な波括弧を使った記法を使うと、 任意のアクセス方法で 変数 の補間を行うことができます。

任意のスカラー変数や、配列の要素、オブジェクトのプロパティ (static かそうでないかは問いません) の文字列表現を、この記法に含めることができます。 式は文字列の外部に現れるものと同じやり方で書くことができ、 `{` と `}` で囲みます。 `{` はエスケープできないので、 この記法は `{` のすぐ後に `$` が続く場合にのみ認識されます。 `{$` を使いたい場合は `{\$` と書くようにしてください。 以下の複数の例を見ると、わかりやすいでしょう:

例19 {} による記法

    <?php
    const DATA_KEY = 'const-key';
    $great = 'fantastic';
    $arr = [
        '1',
        '2',
        '3',
        [41, 42, 43],
        'key' => 'Indexed value',
        'const-key' => 'Key with minus sign',
        'foo' => ['foo1', 'foo2', 'foo3']
    ];

    // 動作しない。出力: This is { fantastic}
    echo "This is { $great}" . PHP_EOL;

    // 動作する。出力: This is fantastic
    echo "This is {$great}" . PHP_EOL;

    // 波括弧を出力に含めるには:
    echo "This is {{$great}}" . PHP_EOL;

    class Square {
        public $width;

        public function __construct(int $width) { $this->width = $width; }
    }

    $square = new Square(5);

    // 動作する
    echo "This square is {$square->width}00 centimeters wide." . PHP_EOL;

    // 動作する。クォートされたキーは波括弧構文でのみ動作する
    echo "This works: {$arr['key']}" . PHP_EOL;

    // 動作する
    echo "This works: {$arr[3][2]}" . PHP_EOL;

    echo "This works: {$arr[DATA_KEY]}" . PHP_EOL;

    // 多次元配列を使う場合、文字列内では常に配列を波括弧で囲む
    echo "This works: {$arr['foo'][2]}" . PHP_EOL;

    echo "This works: {$obj->values[3]->name}" . PHP_EOL;

    echo "This works: {$obj->$staticProp}" . PHP_EOL;

    // 動作しない。出力: C:\directory\{fantastic}.txt
    echo "C:\directory\{$great}.txt" . PHP_EOL;

    // 動作する。出力: C:\directory\fantastic.txt
    echo "C:\\directory\\{$great}.txt" . PHP_EOL;
    ?>

> 注意: この記法を使うと任意の式が使えるので、 可変変数 を使うこともできます。

#### 文字列への文字単位のアクセスと修正

$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 以降では、空の文字列を代入すると 致命的なエラーが発生するようになりました。 これまでのバージョンでは、NULL バイトが代入されていました。

警告

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

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

例20 文字列の例

    <?php
    // 文字列の最初の文字を取得します
    $str = 'This is a test.';
    $first = $str[0];
    var_dump($first);

    // 文字列の 3 番目の文字を取得します
    $third = $str[2];
    var_dump($third);

    // 文字列の最後の文字を取得します
    $str = 'This is still a test.';
    $last = $str[strlen($str)-1];
    var_dump($last);

    // 文字列の最後の文字を変更します
    $str = 'Look at the sea';
    $str[strlen($str)-1] = 'e';
    var_dump($str);
    ?>

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

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

    <?php
    $str = 'abc';

    $keys = [ '1', '1.0', 'x', '1x' ];

    foreach ($keys as $keyToTry) {
        var_dump(isset($str[$keyToTry]));

        try {
            var_dump($str[$keyToTry]);
        } catch (TypeError $e) {
            echo $e->getMessage(), PHP_EOL;
        }

        echo PHP_EOL;
    }
    ?>

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

    bool(true)
    string(1) "b"

    bool(false)
    Cannot access offset of type string on string

    bool(false)
    Cannot access offset of type string on string

    bool(false)

    Warning: Illegal string offset "1x" in Standard input code on line 10
    string(1) "b"

> 注意:

> その他の型の変数 (配列や、適切なインターフェイスを実装したオブジェクトを除く) に対して `[]` や `{}` でアクセスすると、何もメッセージを出さずに単に `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 が文字列に対して特定のエンコーディングを強制しないのなら、 いったいどのようにして文字列リテラルをエンコードしているのでしょう? たとえば、文字列 `"á"` と同等なのは `"\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` (大文字小文字を区別しません) が含まれる文字列のうち、 その文字で数値を区切っている場合、科学的記法で記された数値とみなされます。 この場合、予期しない結果が発生するかもしれません。

> 例1 科学的記法の比較

>     <?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` の組を引数とします。

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

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

> 注意:

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

例1 シンプルな配列定義

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

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

    var_dump($array1, $array2);
    ?>

key は、int または stringです。 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"
    }

例7 負のインデックスの例

負の整数キー `n` を代入すると、PHP は次のキーを `n+1` に代入します。

    <?php
    $array = [];

    $array[-5] = 1;
    $array[] = 2;

    var_dump($array);
    ?>

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

    array(2) {
      [-5]=>
      int(1)
      [-4]=>
      int(2)
    }

警告

PHP 8.3.0 より前のバージョンでは、負の整数キー `n` を代入すると、 次のキーは `0` に代入されていました。 そのため、前の例は次のように出力されていました:

    array(2) {
      [-5]=>
      int(1)
      [0]=>
      int(2)
    }

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

配列の要素へのアクセスには `array[key]` 構文を使います。

例8 配列の要素へのアクセス

    <?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 以降はサポートされなくなっています。

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

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

    $secondElement = getArray()[1];

    var_dump($secondElement);
    ?>

> 注意:

> 配列に定義されていないキーへアクセスしたときの挙動は、 未定義の変数にアクセスしたときと同じです。 つまり、`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[key] = value;
    $arr[] = value;
    // key は string または
    // intのどちらかです。
    // value の型は、何でもかまいません。

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

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

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

ある値を変更するには、 新しい値に値を代入します。特定のキー/値の組を削除したい場合には、 unset() を使用する必要があります。

例10 角括弧と配列の使用

    <?php
    $arr = array(5 => 1, 12 => 2);

    $arr[] = 56;    // このスクリプトのこの位置に記述した場合、
                    // $arr[13] = 56; と同じです

    $arr["x"] = 42; // キー"x"の新しい要素を配列に追加します

    unset($arr[5]); // 配列から要素を削除します

    var_dump($arr);

    unset($arr);    // 配列全体を削除します

    var_dump($arr);
    ?>

> 注意: キーを省略した場合、キーは使用されている整数添字の最大値 + `1` になります。配列に正の整数添字が存在しない場合は、 キーは `0` となります。 PHP 8.3.0 以降では、負の整数になることもあります。

> 次のキー生成において、オフセットとして使われる整数値 (添字の最大値) に対応するエントリーが、 必ずしも配列内に存在するわけではないことに注意してください。 しかし、その値は、多くの場合、 配列にある整数のキー値の最大値と等しいはずです。以下に例を示します。

>     <?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() を使って分解することができます。 これらの言語構造は、 配列を個別の値に分解する用途に使えます。

例11 配列の分解

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

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

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

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

例12 foreach での配列の分解

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

    foreach ($source_array as [$id, $name]) {
        echo "{$id}: '{$name}'\n";
    }
    ?>

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

例13 要素を無視する

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

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

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

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

例14 連想配列の分解

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

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

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

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

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

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

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

例15 2つの変数の入れ替え

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

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

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

> 注意:

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

> 注意:

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

> 注意:

> スカラー値を分解すると、全ての変数に `null` が代入されます。

### 有用な関数

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

> 注意:

> unset()関数は配列のキーを削除することが出来ます。 ただし、これによってインデックスの再構築が行われるわけではないことに 注意してください。 "通常の整数添字" (0 から始まり、1 つずつ増加) のみを使用している場合、 array_values() を用いてインデックスを再構築することができます。

> 例16 中間にある要素を unset する

>     <?php
>     $a = array(1 => 'one', 2 => 'two', 3 => 'three');

>     /* これにより配列は以下の様に定義されます。
>        $a = array(1 => 'one', 3 => 'three');
>        以下ではありません：
>        $a = array(1 => 'one', 2 =>'three');
>     */
>     unset($a[2]);
>     var_dump($a);

>     $b = array_values($a);
>     // $b は、array(0 => 'one', 1 =>'three')となります
>     var_dump($b);
>     ?>

配列専用の制御構造として `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 はそれを解釈できなくなってしまいます。

例17 キーのクォート

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

この具体例を以下に示します。

例18 その他の例

    <?php
    // エラーを全て表示するよう設定
    error_reporting(E_ALL);

    $arr = array('fruit' => 'apple', 'veggie' => 'carrot');

    // 正しい
    echo $arr['fruit'], PHP_EOL;  // apple
    echo $arr['veggie'], PHP_EOL; // carrot

    // 間違い。未定義の定数fruitを使用しているため動作せず、
    // PHP がエラーを発生させます。
    //
    // Error: Undefined constant "fruit"
    try {
        echo $arr[fruit];
    } catch (Error $e) {
        echo get_class($e), ': ', $e->getMessage(), PHP_EOL;
    }

    // 検証のため、定数を定義してみましょう。
    // fruitという名前の定数に値'veggie'を代入します。
    define('fruit', 'veggie');

    // ここでは、出力が異なることに注意してください。
    echo $arr['fruit'], PHP_EOL;  // apple
    echo $arr[fruit], PHP_EOL;    // carrot

    // 以下は文字列の中であるためOKです。定数は、文字列の中では解釈されな
    // いため、エラーはここでは発生しません。
    echo "Hello $arr[fruit]", PHP_EOL;      // Hello apple

    // 例外が１つあり、文字列の中で波括弧で配列を括った場合には、
    // 定数が解釈されます
    echo "Hello {$arr[fruit]}", PHP_EOL;    // Hello carrot
    echo "Hello {$arr['fruit']}", PHP_EOL;  // Hello apple

    // 文字列結合で同じことをすることもできます
    echo "Hello " . $arr['fruit'], PHP_EOL; // Hello apple
    ?>

    <?php
    // これは動作せず、以下のようなパースエラーを発生します:
    // Parse error: parse error, expecting T_STRING' or T_VARIABLE' or T_NUM_STRING'
    // 文字列の中でスーパーグローバルを使用した場合も無論同様です。
    print "Hello $arr['fruit']";
    print "Hello $_GET['foo']";
    ?>

構文 で説明した通り、角括弧 ('`[`' および '`]`') の間には、式がなければなりません。つまり、 次のように書けるということです。

    <?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` と等しいこと等によります。

##### では、なぜ間違っているのでしょう?

将来的に、PHP 開発チームが他の定数またはキーワードを追加したいと思うかもしれず、 問題となる可能性があります。例えば、現在でも、 単語 `empty` および `default`を使用することはできません。 これは、これらが特別な 予約済みのキーワードであるためです。

> 注意: 二重引用符で括られた string の中では 引用符で配列の添字を括らないことができ、このため、 `"$foo[bar]"` は有効です。 この理由の詳細については、上記の例や 文字列中での変数のパースを参照ください。

### 配列への変換

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

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

例19 配列への変換

    <?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` バイトは、以下のような予期せぬ振る舞いをすることがあります:

例20 オブジェクトを配列にキャストする

    <?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 以降で利用可能です。これは、スプレッド演算子とも呼ばれます。

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

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

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

    var_dump($arr1, $arr2, $arr3, $arr4, $arr5, $arr6);
    ?>

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

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

    <?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 の配列型は、いろいろな使い方ができます。配列の強力な機能を示すため、 ここでいくつかの例を紹介します。

例23 多様な配列

    <?php
    // これは、
    $a = array( 'color' => 'red',
                'taste' => 'sweet',
                'shape' => 'round',
                'name'  => 'apple',
                4        // キーは0になります
              );

    $b = array('a', 'b', 'c');

    var_dump($a, $b);

    // 完全にこれと同じです。
    $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') となります

    var_dump($a, $b);
    ?>

例24 array() の使用例

    <?php
    // マップを行う配列
    $map = array( 'version'    => 4,
                  'OS'         => 'Linux',
                  'lang'       => 'english',
                  'short_tags' => true
                );
    var_dump($map);

    // 数値キーのみを有する
    // これは、array(0 => 7, 1 => 8, ...) と同じです
    $array = array( 7,
                    8,
                    0,
                    156,
                    -10
                  );
    var_dump($array);

    $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で上書きされます
                      );
    var_dump($switching);

    // 空の配列
    $empty = array();
    var_dump($empty);
    ?>

例25 コレクション

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

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

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

    <?php
    $colors = array('red', 'blue', 'green', 'yellow');

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

    print_r($colors);
    ?>

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

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

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

例27 1 から始まる添字

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

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

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

例28 配列に代入する

    <?php
    // ディレクトリから全てのアイテムを配列に代入する
    $handle = opendir('.');
    while (false !== ($file = readdir($handle))) {
        $files[] = $file;
    }
    closedir($handle);

    var_dump($files);
    ?>

配列には順番が付けられます。異なったソート関数を用いて順番を変更することも可能です。 より詳細な情報については、配列関数 を参照ください。 count() 関数を使用することで、 配列の要素数を数えることが可能です。

例29 配列のソート

    <?php
    sort($files);
    print_r($files);
    ?>

配列の値は何でも良いため、その値を他の配列とすることも可能です。 これにより、再帰的な配列や多次元の配列を作成することが可能です。

例30 再帰および多次元配列

    <?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"
        )
    );
    var_dump($fruits);

    // 上の配列の内容を取得するための例
    echo $fruits["holes"][5];    // "second" を表示します
    echo $fruits["fruits"]["a"]; // "orange" を表示します
    unset($fruits["holes"][0]);  // "first"  を削除します

    // 新しい多次元配列を作成します
    $juices["apple"]["green"] = "good";
    var_dump($juices);
    ?>

配列への代入においては、常に値がコピーされることに注意してください。 配列をリファレンスでコピーする場合には、 リファレンス演算子を使う必要があります。

例31 配列のコピー

    <?php
    $arr1 = array(2, 3);
    $arr2 = $arr1;
    $arr2[] = 4; // $arr2 が変更されます。
                 // $arr1 は array(2,3) のままです。

    $arr3 = &$arr1;
    $arr3[] = 4; // $arr1 と $arr3 は同じ内容になります。

    var_dump($arr1, $arr2, $arr3);
    ?>

## オブジェクト

### オブジェクトの初期化

オブジェクトを初期化するためには、`new` 命令によりオブジェクトのインスタンスを変数に作成します。

例1 オブジェクトの作成

    <?php
    class foo
    {
        function do_foo()
        {
            echo "foo を実行します。";
        }
    }

    $bar = new foo;
    $bar->do_foo();
    ?>

詳細な事項については、 クラスおよびオブジェクト のセクションを参照ください。

### オブジェクトへの変換

オブジェクトがオブジェクトに変換される場合はなにも修正されません。 オブジェクト以外の型の値がオブジェクトに変換される時には、stdClass というビルトインクラス（予めPHPの内部で定義されているクラス）のインスタンスが新しく生成されます。 その際、値が null の場合は新しいインスタンスは空となります。 また、配列がオブジェクトに変換される場合、配列のキーと値がそれぞれオブジェクトのプロパティ名とその値となります。 PHP 7.2.0 より前のバージョンでは、数値のキーの場合プロパティ名によるアクセスはできなかった点に注意して下さい。

例2 オブジェクトにキャストする

    <?php
    $obj = (object) array('1' => 'foo');
    var_dump(isset($obj->{'1'})); // outputs 'bool(true)'

    // PHP 8.1 以降は非推奨
    var_dump(key($obj)); // outputs 'string(1) "1"'
    ?>

上記以外の値の場合には、`scalar` という名前のメンバ変数が値を格納します。

例3 `(object)` によるキャスト

    <?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 の場合) を持つ配列が生成されます。 それ以外のキャストを行っても、エラーが発生します。

## リソース

resource は特別な変数であり、外部リソースへのリファレンスを保持しています。 リソースは、特別な関数により作成され、使用されます。 これらの関数および対応する全ての resource 型の一覧については、 付録 を参照ください。

get_resource_type() も参照ください。

### リソースへの変換

resource 型は、オープンされたファイル、データベース接続、 イメージキャンバスエリアのような特殊なハンドルを保持するため、 他の値を resource に変換することはできません。

### リソースの開放

Zend エンジンの一部であるリファレンスカウンティングシステムのおかげで、 ある resource がもう参照されなくなった場合に (Java と全く同様に)、 そのリソースは自動的に削除されます。この場合、このリソースが作成した 全てのリソースは、ガベージコレクタにより開放されます。 このため、free_result 関数を用いて手動でメモリを開放する必要が生じるのはまれです。

> 注意: 持続的データベース接続は特別で、ガベージコレクタにより破棄されません。 持続的接続 も参照ください。

## コールバック / Callable

callable は、 別の関数への引数として渡される関数またはメソッドを参照するものです。 これらは、callable 型を宣言することで表されます。

    <?php
    function foo(callable $callback) {
        $callback();
    }
    ?>

関数によっては、コールバック関数をパラメータとして受け入れるものがあります。 例として array_map(), usort(), preg_replace_callback() が挙げられます。

### callable の作成

callable は、呼び出し可能な何かを表す型です。 コールバック関数をパラメータとして期待する関数や、 メソッドの引数として渡すことができますし、 直接呼び出すこともできます。 callable 型は、 クラスのプロパティの型宣言には使えません。 代わりに、Closure を型宣言に使ってください。

callable は、複数の異なる方法で作成できます:

- Closure オブジェクト
- 関数またはメソッドの名前を含む文字列
- 配列。クラス名または object をインデックス 0 に、メソッド名をインデックス 1 に含みます。
- __invoke() マジックメソッドを実装した object

Closure オブジェクトは、 無名関数、 アロー関数、 第一級callableを生成する記法、 もしくは Closure::fromCallable() メソッドを使って作成できます。

> 注意: 第一級callableを生成する記法 は、PHP 8.1.0 以降でのみ利用可能です。

例1 Closure を使ったコールバックの例

    <?php
    // Using anonymous function syntax
    $double1 = function ($a) {
        return $a * 2;
    };

    // Using first-class callable syntax
    function double_function($a) {
        return $a * 2;
    }
    $double2 = double_function(...);

    // Using arrow function syntax
    $double3 = fn($a) => $a * 2;

    // Using Closure::fromCallable
    $double4 = Closure::fromCallable('double_function');

    // Use the closure as a callback here to
    // double the size of each element in our range
    $new_numbers = array_map($double1, range(1, 5));
    print implode(' ', $new_numbers) . PHP_EOL;

    $new_numbers = array_map($double2, range(1, 5));
    print implode(' ', $new_numbers) . PHP_EOL;

    $new_numbers = array_map($double3, range(1, 5));
    print implode(' ', $new_numbers) . PHP_EOL;

    $new_numbers = array_map($double4, range(1, 5));
    print implode(' ', $new_numbers);

    ?>

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

    2 4 6 8 10
    2 4 6 8 10
    2 4 6 8 10
    2 4 6 8 10

callable は、 関数名や static メソッドを含む文字列でも表現できます。 ビルトイン関数、またはユーザー定義関数も使えます。 但し、以下のような言語構造は除きます: array(), echo, empty(), eval(), isset(), list(), print, unset()

static メソッドは、クラスの object 型をインスタンス化せずに使えます。 クラス名をインデックス 0 に、 メソッド名をインデックス 1 に配置した配列を作成するか、 `'ClassName::methodName'` のような、 スコープ解決演算子 `::` を使った特殊構文が使えます。

インスタンス化された object のメソッドは、object をインデックス 0 に、 メソッド名をインデックス 1 に配置した配列を作成することで、 callable にできます。

Closure オブジェクトと callable 型の主な違いは、 Closure オブジェクトがスコープに依存せず常に呼び出せるのに対し、 callable はスコープに依存する場合があり、 直接呼び出せない可能性がある点です。 Closure が、callable を作成する望ましい方法です。

> 注意: Closure オブジェクトは、 それが作成されたスコープにバインドされますが、 クラスメソッドを文字列または配列で参照する callable は、 それらが呼び出されたスコープの内部で解決されます。 callable を private または protected メソッドから作成し、 クラスのスコープ外から呼び出せるようにするには、 Closure::fromCallable() または、 第一級callableを生成する記法 を使います。

PHP は、コールバック引数として使えるものの、 直接は呼び出せない callable を作成できます。 これらはコンテキスト依存の callable であり、 例えば `'parent::method'` や `["static", "method"]` の形で、クラスの継承階層におけるクラスメソッドを参照します。

> 注意: PHP 8.2.0 以降では、 コンテキスト依存の callable は推奨されなくなりました。 `'parent::method'` を `parent::class . '::method'` 形式に置き換えることでコンテキスト依存を除去するか、 第一級callableを生成する記法 を使ってください。

例2 call_user_function() を使って、様々なタイプの callable を呼び出す

    <?php

    // An example callback function
    function my_callback_function() {
        echo 'hello world!', PHP_EOL;
    }

    // An example callback method
    class MyClass {
        static function myCallbackMethod() {
            echo 'Hello World!', PHP_EOL;
        }
    }

    // Type 1: Simple callback
    call_user_func('my_callback_function');

    // Type 2: Static class method call
    call_user_func(['MyClass', 'myCallbackMethod']);

    // Type 3: Object method call
    $obj = new MyClass();
    call_user_func([$obj, 'myCallbackMethod']);

    // Type 4: Static class method call
    call_user_func('MyClass::myCallbackMethod');

    // Type 5: Static class method call using ::class keyword
    call_user_func([MyClass::class, 'myCallbackMethod']);

    // Type 6: Relative static class method call
    class A {
        public static function who() {
            echo 'A', PHP_EOL;
        }
    }

    class B extends A {
        public static function who() {
            echo 'B', PHP_EOL;
        }
    }

    call_user_func(['B', 'parent::who']); // deprecated as of PHP 8.2.0

    // Type 7: Objects implementing __invoke can be used as callables
    class C {
        public function __invoke($name) {
            echo 'Hello ', $name;
        }
    }

    $c = new C();
    call_user_func($c, 'PHP!');
    ?>

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

    hello world!
    Hello World!
    Hello World!
    Hello World!
    Hello World!

    Deprecated: Callables of the form ["B", "parent::who"] are deprecated in script on line 41
    A
    Hello PHP!

> 注意: 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` になります。

### `(void)` による値の破棄

`(void)` 構文を使うと、式の結果を明示的に破棄できます。 これは、戻り値を無視するのが意図的であることを示すのに便利です。 特に、NoDiscard アトリビュートが指定された関数やメソッドを呼び出す場合に役立ちます。

他のキャストとは異なり、`(void)` は値を別の型に変換せず、 値を生成しません。これは文であり、式の一部として使うことはできません。

例1 戻り値を破棄する

    <?php
    #[\NoDiscard]
    function process(): bool {
        return true;
    }

    (void) process(); // 戻り値を明示的に破棄する
    ?>

## Never

never は、 関数が戻ってこないことを示す戻り値の型です。 これは、関数の中で exit() がコールされるか、 例外がスローされるか、 無限ループに入るかのいずれかであることを意味します。 よって、この型は union 型 の一部として指定することが出来ません。 PHP 8.1.0 以降で利用できます。

never は、 型理論の用語で言うと、ボトム型にあたります。 つまり、全ての他の型の部分型であり、 継承する際に他の戻り値の型を置き換えることができます。

## クラス内での関係を示す相対型

以下の型宣言は、クラスの内部でのみ使えます。

### self

値が、型宣言が行われているクラスと同じクラスのインスタンスでなければいけません。

### parent

値が、型宣言が行われたクラスの、親クラスのインスタンスでなければいけません。

### static

値が、メソッドが呼び出されているクラスと同じインスタンスでなければならないことを示す、戻り値でのみ指定できる型です。PHP 8.0.0 以降で利用できます。

## シングルトン型

シングルトン型は、ただひとつの値のみを受け入れる型です。 PHP はふたつのシングルトン型をサポートしています。 PHP 8.0.0 以降でサポートされた `false` 型と、 PHP 8.2.0 以降でサポートされた `true` 型です。

警告

PHP 8.2.0 より前のバージョンでは、 false型は union 型 の一部としてのみ使える型でした。

> 注意: カスタムのシングルトン型を定義することはできません。 そうしたい場合、列挙型(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;
>     }

>     foreach(gen() as $value) {
>         echo $value, "\n";
>     }
>     ?>

## 型宣言

関数のパラメータや戻り値、 クラスのプロパティ (PHP 7.4.0 以降)、クラス定数 (PHP 8.3.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 型の中で、シングルトン型 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 型を追加しなければならなくなるため、おすすめできません。 この振る舞いは、PHP 8.4 以降は推奨されなくなっています。

> 例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 型や、 never 型を複合型で使うとエラーになります。
- 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 と互換性はない。
    ?>

### 型キャスト

型キャストは、変換しようとする型の名前を括弧で括り、 キャストする変数の前に置くことで、値を別の型に変換するものです。

例2 型キャストの例

    <?php
    $foo = 10;          // $foo は整数です
    $bar = (bool) $foo; // $bar は boolean です

    var_dump($bar);
    ?>

使用可能なキャストを以下に示します:

- `(int)` - 整数(int) へのキャスト
- `(bool)` - 論理値(bool) へのキャスト
- `(float)` - float へのキャスト
- `(string)` - 文字列(string) へのキャスト
- `(array)` - 配列(array) へのキャスト
- `(object)` - オブジェクト(object) へのキャスト
- `(unset)` - NULL へのキャスト

PHP 8.5.0 以降では `(void)` キャストも使用できますが、これは値の変換ではありません。 式の結果を明示的に破棄する文として使用します。

警告

`(integer)` は、`(int)` のエイリアスです。 `(boolean)` は、`(bool)` のエイリアスです。 `(binary)` は、`(string)` のエイリアスです。 `(double)` と `(real)` は、`(float)` のエイリアスです。 これらのキャストは、正規化された型の名前を使っていません。 そのため PHP 8.5.0 以降では推奨されなくなりました。

警告

キャストのエイリアス `(real)` を使うことは、PHP 7.4.0 以降は推奨されなくなり、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";
    ?>

ある変数を文字列にキャストする代わりに、 二重引用符で括ることもできます。

例3 異なるキャストの仕組み

    <?php
    $foo = 10;            // $foo は整数です
    $str = "$foo";        // $str は文字列です
    $fst = (string) $foo; // $fst も文字列です

    // これは、"they are the same"を出力します
    if ($fst === $str) {
        echo "they are the same", PHP_EOL;
    }
    ?>

型の間でキャストを行う際の動作は、必ずしも明確ではありません。 詳細については、以下の節を参照ください:

- 論理値への変換
- 整数への変換
- 浮動小数点数への変換
- 文字列への変換
- 配列への変換
- オブジェクトへの変換
- リソース型への変換
- NULL への変換
- `(void)` による値の破棄
- 型の比較表

> 注意: PHP では配列の添字と同じ構文を使用した文字列へのアクセスをサポートしているので、次の例はあらゆるバージョンの PHP で成立します:

> 例4 文字列で配列の添字を使う

>     <?php
>     $a    = 'car'; // $a は文字列です
>     $a[0] = 'b';   // $a はここでも文字列です
>     echo $a;       // bar
>     ?>

> 詳細は、 文字列への文字単位のアクセス を参照ください。

# 変数

## 目次

- 基本的な事
- 定義済みの変数
- 変数のスコープ
- 可変変数
- 外部から来る変数

## 基本的な事

PHP の変数はドル記号の後に変数名が続く形式で表されます。 変数名は大文字小文字を区別します。

変数名は、文字 (`A-Z`, `a-z`, 128から255 までのバイト) かアンダースコアで始まり、 任意の数の文字、 数字、アンダースコアが続きます。正規表現を使うと、これは次の ように表現することができます。 `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$`

> 注意: PHP は Unicode の変数名はサポートしていませんが、 (UTF-8のような)文字エンコーディングによっては、 マルチバイト文字の全てのバイトを可能な範囲にまでエンコードする場合があり、 その結果正しい変数名になる場合があります。

> 注意: `$this` は特別な変数であり、ここに代入することはできません。 PHP 7.1.0 より前のバージョンでは、 (可変変数 を使った) 間接的な代入 が可能でした。

ヒント

ユーザーレベルでの命名の手引き も参照ください。

例1 有効な変数名

    <?php
    $var = 'Bob';
    $Var = 'Joe';
    echo "$var, $Var";      // outputs "Bob, Joe"

    $_4site = 'not yet';    // valid; starts with an underscore
    $täyte = 'mansikka';    // valid; 'ä' is (Extended) ASCII 228.

例2 無効な変数名

    <?php
    $4site = 'not yet';     // invalid; starts with a number

PHP は、任意のバイトの連続を変数名として受け入れます。 既に述べたルールに従わない変数名は、実行時にのみ動的にアクセスできます。 アクセスする方法については 可変変数 を参照ください。

例3 曖昧な変数名にアクセスする

    <?php
    ${'invalid-name'} = 'bar';
    $name = 'invalid-name';
    echo ${'invalid-name'}, " ", $$name;

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

    bar bar

デフォルトでは、変数に代入されるのは常にその値です。 これは、つまり、ある変数にある式を代入する際、元の式の 値全体がコピーされる側の変数にコピーされるということです。 これは、例えば、ある変数の値を他の変数に代入した後で、 これらの変数の1つを変更しても他の変数には影響を与えないという ことを意味します。この種の代入に関するより詳細な情報については、 式 を参照ください。

PHP には、変数に値の代入を行う別の方法も存在します。それは、 参照による代入 です。 この場合、新規の変数は元の変数を参照するだけです。 (言いかえると、元の変数の"エイリアスを作る"または元の変数を"指す") 新規の変数への代入は、元の変数に影響し、その逆も同様となります。

参照により代入を行うには、代入する変数(ソース変数)の先頭に アンパサンドを加えます。たとえば、次の簡単なコードは '`My name is Bob`'を二度出力します。

    <?php
    $foo = 'Bob';              // 値'Bob'を$fooに代入する。
    $bar = &$foo;              // $fooを$barにより参照
    $bar = "My name is $bar";  // $barを変更...
    echo $bar . PHP_EOL;
    echo $foo . PHP_EOL;       // $fooも変更される。

注意すべき重要な点として、変数のみが参照により代入できる ということがあります。

    <?php
    $original = 25;
    $ref1 = &$original;        // これは有効な代入です。
    $ref2 = &(24 * 7);         // 無効です。名前のない式を参照しています。

    <?php
    // 関数宣言でリファレンスを返すことを示す & がないことに注意してください。
    // つまり、この関数はリファレンスを返さないので、結果をリファレンスで代入できません。
    function test()
    {
       $original = 25;
       return $original;
    }

    // 注意: notice が発生しますが、リファレンスでない値が代入されます。
    $result1 = &test();        // 無効。なぜなら、test() は変数をリファレンスで返していないからです。
    var_dump($result1);

    // この関数はリファレンスを返すものとして定義されていますが、変数を返してはいません。
    function &test2()
    {
        return 26;             // 無効。なぜなら、返される値が変数のリファレンスではないからです。
    }

    // 注意: リファレンスでない値が代入されます。
    $result2 = &test2();
    var_dump($result2);

PHP では変数を初期化する必要はありませんが、 そうするのはとてもよいことです。 初期化されていない場合、 `E_WARNING` (PHP 8.0.0 より前のバージョンでは `E_NOTICE`) が発生します。 未定義の変数は、デフォルト値 `null` を持ちます。 変数が既に初期化済みかどうかを検知するには、 言語構造 isset() が使えます。

例4 未初期化の変数のデフォルト値

    <?php
    // Unset AND unreferenced (no use context) variable.
    var_dump($unset_var);

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

    Warning: Undefined variable $unset_var in ...
    NULL

PHP は、未定義の変数からの配列の autovivification (新しい配列の自動生成) を許可しています。 未定義の変数に要素を追加する操作は、 新しい配列を生成し、警告は発生しません。

例5 未定義の変数から配列を自動生成する

    <?php
    $unset_array[] = 'value'; // 警告は発生しません
    var_dump($unset_array);

警告

初期化されていない変数のデフォルト値に依存すると、そのファイルを include している別のファイルで同名の変数が使用されていた場合に問題を起こします。

変数は、言語構造 unset() を使って破棄できます。

変数に関連した関数については、 関数リファレンス を参照ください。

## 定義済みの変数

PHPは、多くの 定義済みの変数 を提供します。 PHP には、(使用する場合)Webサーバー、環境変数、 ユーザー入力からの変数を値とする定義済みの配列が追加されています。 これらの配列は、自動的に全ての スコープで利用可能です。このため、これらは "スーパーグローバル" といわれることもあります。 (PHPには、ユーザー定義のスーパーグローバルという機構はありません。) スーパーグローバルの一覧 も参照ください。

> 注意: 可変変数

> 可変変数として スーパーグローバルを使うことはできません。

variables_orderに ある変数が設定されていない場合、これらに対応するPHPの定義済み 変数も空のままとなります。

## 変数のスコープ

変数のスコープは、その変数が定義されたコンテキストです。 PHP には関数スコープとグローバルスコープがあります。 関数の外部で定義されたあらゆる変数は、グローバルスコープになります。 ファイルが include された場合、 そのファイルに含まれるコードは、 include が行われた行の変数のスコープを引き継ぎます。

例1 グローバル変数のスコープの例

    <?php
    $a = 1;

    include 'b.inc'; // 変数 $a は b.inc で利用できます。

名前付きの関数や 無名関数 の内部で作られた変数は、関数の内部のスコープでのみ使えます。 しかし、アロー関数 は親のスコープの変数を内部で利用できるようにするために、 変数をバインドします。 ファイルの include が呼び出し側のファイルで発生した場合、 呼び出されたファイルに含まれる変数は、 関数を呼び出す内部で定義されたかのように利用できます。

例2 ローカル変数のスコープ

    <?php
    $a = 1; // グローバルスコープ

    function test()
    {
        var_dump($a); // $a は、ローカルスコープの $a を参照しているので未定義です
    }

    test();

このスクリプトは、未定義の変数があるという `E_WARNING` (PHP 8.0.0 より前のバージョンでは `E_NOTICE`) を生成します。 これは、echo 命令がローカル版の $a 変数を参照しているにもかかわらず、こ のスコープでは値が代入されていないからです。この動作は、特にローカ ルな定義で上書きしない限りグローバル変数が自動的に関数で使用可能で ある C 言語と少々異なっていると気がつかれるかもしれません。C言語の ような場合、グローバル変数を不注意で変更してしまうという問題を生じ る可能性があります。PHP では、グローバル変数は、関数の内部で使用す る場合、関数の内部でグローバルとして宣言する必要があります。

### `global` キーワード

`global` キーワードは グローバルスコープの変数をローカルスコープにバインドするために使います。 このキーワードは変数のリストや、単一の変数を指定できます。 グローバル変数と同じ名前の変数を参照するローカル変数が作られます。 グローバル変数が存在しない場合、グローバルスコープの変数が作られ、 `null` が代入されます。

例3 `global` の使用

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

    function Sum()
    {
        global $a, $b;

        $b = $a + $b;
    }

    Sum();
    echo $b;

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

    3

関数の内部で $a、$b をグローバル宣言を行うことにより、両変数への参照は、グローバル変数 の方を参照することになります。ある関数により操作できるグローバル変 数の数は無制限です。

グローバルスコープから変数をアクセスする2番目の方法は、PHPが定義す る配列$GLOBALSを使用することです。先の例は、次 のように書き換えることができます。

例4 globalのかわりに$GLOBALSを使用する

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

    function Sum()
    {
        $GLOBALS['b'] = $GLOBALS['a'] + $GLOBALS['b'];
    }

    Sum();
    echo $b;

配列$GLOBALSは連想配列であり、グローバル変数の 名前がキー、その変数の内容が配列要素の値となっています。 $GLOBALS は スーパーグローバル であるため、$GLOBALSは全てのスコープに存在します。 以下にスーパーグローバルの効果を示す例を示します。

例5 スーパーグローバルとスコープの例

    <?php
    function test_superglobal()
    {
        echo $_POST['name'];
    }

> 注意: `global` キーワードを関数の外部で使ってもエラーにはなりません。 そのファイルが関数の内部からインクルードされたときに使うことができます。

### static 変数の使用

変数のスコープに関する別の重要な機能は、static (静的) 変数です。static 変数はローカル関数スコープのみに 存在しますが、プログラム実行がこのスコープの外で行われるようになっ てもその値を失いません。次の例を見てください。

例6 static 変数が必要な場面の例

    <?php
    function test()
    {
        $a = 0;
        echo $a . PHP_EOL;
        $a++;
    }

    test();
    test();
    test();

この関数は、コールされる度に$aを `0`にセットし、`0` を出力するのでほとん ど役にたちません。変数を1増やす $a++ は、関数から外に出ると変数 $aが消えてしまうために目的を達成しません。現在 のカウントの追跡ができるようにカウント関数を使用できるようにするた めには、変数$aを static として宣言します。

例7 static 変数の使用例

    <?php
    function test()
    {
        static $a = 0;
        echo $a . PHP_EOL;
        $a++;
    }

    test();
    test();
    test();

こうすると、$a は関数が最初にコールされたときにのみ初期化され、 `test()` 関数がコールされるたびに $a の値を出力してその値を増加させます。

static 変数は、再帰関数を実現する1つの手段としても使用されます。 次の簡単な関数は、中止す るタイミングを知るためにstatic変数$countを用いて、 10 回まで再帰を行います。

例8 再帰関数でのstatic変数の使用

    <?php
    function test()
    {
        static $count = 0;

        $count++;
        echo $count . PHP_EOL;
        if ($count < 10) {
            test();
        }
        $count--;
    }

    test();

PHP 8.3.0 より前のバージョンでは、 static 変数には、定数式でのみ初期化できていました。 PHP 8.3.0 以降では、動的な式(例: 関数呼び出し) での初期化も許可されています。

例9 static 変数の宣言

    <?php
    function foo(){
        static $int = 0;          // 正しい
        static $int = 1+2;        // 正しい
        static $int = sqrt(121);  // PHP 8.3.0 以降は正しい

        $int++;
        echo $int;
    }

無名関数の内部にある static 変数は、 その特定の関数のインスタンス内でのみ生き残ります。 コールされるたびに無名関数が再作成される場合、 static 変数は再初期化されます。

例10 無名関数の内部にある static 変数

    <?php
    function exampleFunction($input) {
        $result = (static function () use ($input) {
            static $counter = 0;
            $counter++;
            return "Input: $input, Counter: $counter\n";
        });

        return $result();
    }

    // Calls to exampleFunction will recreate the anonymous function, so the static
    // variable does not retain its value.
    echo exampleFunction('A'); // Outputs: Input: A, Counter: 1
    echo exampleFunction('B'); // Outputs: Input: B, Counter: 1

(オーバーライドされていない場合) 内部でstatic 変数を使ったメソッドも継承されます。 PHP 8.1.0 以降は、継承されたメソッドは、 親クラスのメソッドとstatic 変数を共有するようになりました。 つまり、メソッド内でのstatic 変数も、 static プロパティと同じ振る舞いになったということです。

PHP 8.3.0 以降では、static 変数は任意の式で初期化できるようになりました。 これはたとえば、メソッドをコールすることでも、 static 変数を初期化できるようになったということです。

例11 継承されたメソッドの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 変数のリファレンス

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`命令にも適用されます。 リファレンスはstatic 変数に保存することができません。

    <?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';
    var_dump($a);

可変変数は、変数の値をとり、変数の名前として扱います。上の例では、 hello は、ドル記号を二つ使用することにより、 変数の名前として使用することができます。つまり、

    <?php
    $a = 'hello';
    $$a = 'world';
    var_dump($hello);

ここまでで、二つの変数が定義され、PHP シンボルツリーに定義されてい ます。これらは、"hello" を値とする$aと "world" を値とする$helloです。そこで、次の命令

    <?php
    $a = 'hello';
    $$a = 'world';
    echo "$a {$$a}";

の出力は、次の命令と全く同じとなります。

    <?php
    $a = 'hello';
    $$a = 'world';
    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 {
        public $bar = 'I am bar.';
        public $arr = ['I am A.', 'I am B.', 'I am C.'];
        public $r   = 'I am r.';
    }

    $foo = new Foo();
    $bar = 'bar';
    $baz = ['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";
    echo $foo->{$arr}[1] . "\n";

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

    I am bar.
    I am bar.
    I am bar.
    I am r.
    I am B.

警告

関数やクラスメソッドの内部で、可変変数と 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 . "\n";

    // スカラー式
    const ANOTHER_CONST = CONSTANT . '; Goodbye World';
    echo ANOTHER_CONST . "\n";

    const ANIMALS = array('dog', 'cat', 'bird');
    echo ANIMALS[1] . "\n"; // 出力は "cat"

    // 配列の定数
    define('ANIMALS_DEF', array(
        'dog',
        'cat',
        'bird'
    ));
    echo ANIMALS_DEF[1] . "\n"; // 出力は "cat"

> 注意:

> define() による定数の定義とは反対に、 `const` キーワードで定義した定数はトップレベルのスコープで宣言しなければなりません。 これはコンパイル時に定義されるからです。 つまり、関数、ループ、`if` 文、または `try`/`catch` ブロックの内部では宣言できないということです。

> 注意:

> PHP 8.0.0 より前のバージョンでは、define() 関数を使って定義された定数は、 大文字小文字を区別しません。

### 参考

- クラス定数

## 自動的に定義される定数

PHPには実行されるスクリプトで使用可能な多くの 定義済みの定数があります。 しかし、これらの定数の多くは、種々の拡張モジュールにより作成され、 動的なロードやコンパイル時の組込みにより、これらの拡張モジュールが 使用可能である場合にのみ定義されます。

## マジック定数

使われる場所によって値が変化する定数（マジック定数）がいくつかあります。 例えば、`__LINE__`はスクリプト上において 使われる行によって値が変化します。 これらの "マジック"定数は、実行時に解決される通常の定数とは異なり、コンパイル時に解決されます。 これらの特別な定数は大文字小文字を区別しません。 内容は以下のとおりです:

PHP の "マジック" 定数
名前 | 説明
--- | ---
`__LINE__` | ファイル上の現在の行番号。
`__FILE__` | ファイルのフルパスとファイル名 (シンボリックリンクを解決した後のもの)。 インクルードされるファイルの中で使用された場合、インクルードされるファイルの名前が返されます。
`__DIR__` | そのファイルの存在するディレクトリ。include の中で使用すると、 インクルードされるファイルの存在するディレクトリを返します。 つまり、これは `dirname(__FILE__)` と同じ意味です。 ルートディレクトリである場合を除き、ディレクトリ名の末尾にスラッシュはつきません。
`__FUNCTION__` | 関数名。無名関数の場合は、`{closure}`
`__CLASS__` | クラス名。 クラス名には、そのクラスが宣言されている名前空間も含みます (例 `Foo\Bar`)。 トレイトのメソッド内で `__CLASS__` を使うと、 そのトレイトを use しているクラスの名前を返します。
`__TRAIT__` | トレイト名。 トレイト名には、宣言された名前空間も含みます (例 `Foo\Bar`)。
`__METHOD__` | クラスのメソッド名。
`__PROPERTY__` | プロパティ名。 プロパティフック の内部でのみ使用可能です。
`__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) です */
    print "a = {$a}; b = {$b}; c = {$c}" . PHP_EOL;

    $e = $d = ++$b;     /* 前置加算なので、$d と $e に代入される値は、
                           加算後の $b の値 (6) です */
    print "b = {$b}; d = {$d}; e = {$e}" . PHP_EOL;

    /* ここまでで、$d と $e は、6 です */

    $f = double($d++);  /* $f には、$d が加算される前の値を2倍した値、
                           つまり 2*6 = 12 が、代入されます。 */
    print "d = {$d}; f = {$f}" . PHP_EOL;

    $g = double(++$e);  /* $g には、$e が加算された後の値を2倍した値、
                            つまり 2*7 = 14 が、代入されます。 */
    print "e = {$e}; g = {$g}" . PHP_EOL;

    $h = $g += 10;      /* まず、$g に 10 が加算され、24 になります。
                           代入値 (24) は、$h に代入されます。
                           そして、$h も同様に 24 になります。 */
    print "g = {$g}; h = {$h}" . PHP_EOL;
    ?>

式が、文として扱われることがあります。 この場合、文は、'`式 ;`'、つまり式の後にセミコロンがついた形式です。 `$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 | `&&` | 論理演算子
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` | 論理演算子
(n/a) | `throw` | throw

例1 結合時の評価

    <?php
    $a = 3 * 3 % 5; // (3 * 3) % 5 = 4
    var_dump($a);

    $a = 1;
    $b = 2;
    $a = $b += 3; // $a = ($b += 3) -> $a = 5, $b = 5
    var_dump($a, $b);
    ?>

三項演算子は特に、優先順位を明確にするための括弧が必要となります。

例2 優先順位の明示

    <?php
    $a = true ? 0 : (true ? 1 : 2);
    var_dump($a);

    // PHP 8 以降は以下のように書くことはできません
    // $a = true ? 0 : true ? 1 : 2;
    ?>

演算子の優先順位や結合性は、あくまでも式のグループ分けだけを決めるものであり、評価順を決めるものではありません。 PHP では一般に、式をどの順番で評価するかは決めていません。 そのため、特定の順序で式が評価されることを前提としたコードを書いてはいけません。 PHP のバージョンが変わったり前後のコードが変わったりしたときに、評価順が変わる可能性があるからです。

例3 評価順序は未定義

    <?php
    $a = 1;
    echo $a + $a++; // 2 になるかもしれないし、3 になるかもしれません

    $i = 1;
    $array[$i] = $i++; // インデックス 1 をセットするかもしれないし、インデックス 2 をセットするかもしれません
    ?>

例4 `+`、`-`、`.` の優先順位

    <?php
    $x = 4;
    // 次の行は、予期せぬ結果になることでしょう
    echo "x minus one equals " . $x-1 . ", or so I hope\n";

    // 期待どおりの結果を得るには、括弧を使って優先順位を指定します
    echo "x minus one equals " . ($x-1) . ", or so I hope\n";

    // このようにはできず、TypeError がスローされます
    echo (("x minus one equals " . $x) - 1) . ", or so I hope\n";
    ?>

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

    -1, or so I hope
    -1, or so I hope
    Fatal error: Uncaught TypeError: Unsupported operand types: string - int

例5 PHP 8 より前のバージョンでは、 `+`, `-` and `.` の優先順位は同じ

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

除算演算子 `/` の返す値は float となります。 ただし、ふたつのオペランドがともに int (あるいは int に型変換される 数値形式の文字列) であり、かつ被除数が除数の倍数である場合には整数値を返します。 整数の除算については intdiv() を参照ください。

剰余演算子は、まず両方のオペランドを整数に直してから処理を行います。 浮動小数点の剰余については fmod() を参照ください。

剰余演算子 `%` の結果の符号は、被除数の符号と同じになります。 つまり、`$a % $b` の結果の符号は $a と同じになるということです。

例1 剰余演算子

    <?php
    var_dump(5 % 3);
    var_dump(5 % -3);
    var_dump(-5 % 3);
    var_dump(-5 % -3);
    ?>

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

    int(2)
    int(2)
    int(-2)
    int(-2)

### 参考

- 数学関数

## 加算子/減算子

PHP は 加算子/減算子（前置・後置ともに）をサポートします。 これらの単項演算子は、値をインクリメント(ひとつ増や)したり、デクリメント(ひとつ減ら)したりできます。

加算子/減算子
例 | 名前 | 効果
--- | --- | ---
++$a | 前置加算子 | $a をインクリメントし、$a を返します。
$a++ | 後置加算子 | $a を返し、$a をインクリメントします。
--$a | 前置減算子 | $a をデクリメントし、$a を返します。
$a-- | 後置減算子 | $a を返し、$a をデクリメントします。

例1 インクリメント/デクリメントの例

    <?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'` に変更します。

例2 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() を使えば、こうした暗黙の型変換の影響を受けません。

例3 英数字が浮動小数点数にキャストされる挙動

    <?php
    $s = "5d9";
    var_dump(++$s);
    var_dump(++$s);
    ?>

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

    string(3) "5e0"
    float(6)

上記の出力になる理由は、`"5e0"` という値が float として解釈され、インクリメントされる前に `5.0` にキャストされるためです。

## 代入演算子

代入演算子の基本となるものは "=" です。この演算子に関して最初に 思い付く意味は"等しい"であるかもしれません。しかし、そうではありません。 本当は、左オペランドに右オペランドの式の値を設定する("得て代入する") ことを意味します。

代入式の値は、代入される値です。つまり、"`$a = 3`" の値は、3 です。 これにより、以下のようなトリッキーなことができるようになります。

例1 ネストした代入

    <?php
    $a = ($b = 4) + 5; // $a は 9 に等しくなり、$b には 4 が代入されます
    var_dump($a);
    ?>

基本代入演算子に加えて、全ての 演算子、配列結合および文字列演算子に関して 「複合演算子」があります。 これにより、式の中の値を使用し、その値をその式の結果とすることができます。 例えば、

例2 複合代入

    <?php
    $a = 3;
    $a += 5; // $a を 8 にセットします。$a = $a + 5; と同じです。
    $b = "Hello ";
    $b .= "There!"; // $bを"Hello There!"にセットします。$b = $b . "There!";と同じです。

    var_dump($a, $b);
    ?>

代入は、元の変数を新しい変数にコピーする(値による代入)ため、 片方の変数に対する変更はもう片方に影響を与えないということに 注意してください。この動作により、密なループの内側で大きな配列のようなものを コピーする必要がある場合には問題を生じる可能性があります。

PHP では通常は値による代入になりますが、 オブジェクトは参照で代入されます。 オブジェクトを明示的にコピーするには clone キーワードを使います。

### 参照による代入

参照による代入もサポートしており、 "$var = &$othervar;" 構文で使うことができます。 参照による代入とは、両方の変数が同じデータを指すようにするということです。 データのコピーは発生しません。

例3 参照による代入

    <?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 の結果を参照で代入するとエラーが発生します。

例4 new 演算子の参照

    <?php
    class C {}

    $o = &new C;
    ?>

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

    Parse error: syntax error, unexpected token ";", expecting "("

参照に関する詳細な情報やその使い方については、このマニュアルの リファレンスに関する説明 をご覧ください。

### 算術代入演算子

例 | 同一の結果になる操作 | 演算
--- | --- | ---
$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, PHP_EOL; // 出力は '5'

    echo "12" ^ "9", PHP_EOL; // 出力はバックスペース文字 (ascii 8)
                              // ('1' (ascii 49)) ^ ('9' (ascii 57)) = #8

    echo "hallo" ^ "hello", PHP_EOL; // 出力は、ascii コード #0 #4 #0 #0 #0
                                     // 'a' ^ 'e' = #4

    echo 2 ^ "3", PHP_EOL; // 出力は 1
                           // 2 ^ ((int) "3") == 1

    echo "2" ^ 3, PHP_EOL; // 出力は 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\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

例1 比較演算子

    <?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 のほうが常に大きくなります

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

例3 一般的な配列の比較

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

### 三項演算子

もうひとつの条件演算子として "?:"（あるいは三項）演算子があります。

例4 デフォルト値を設定する

    <?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 以降は、三項演算子はどの演算とも結合しなくなっています。

> 例5 三項演算子のわかりにくい挙動

>     <?php
>     // ぱっと見た感じでは、これは 'true' と表示されると思うでしょう。
>     echo (true ? 'true' : false ? 't' : 'f');

>     // しかし、PHP 8.0.0 より前のバージョンでは、実際には上の出力結果は 't' です。
>     // なぜなら、三項演算子は左結合だったからです。

>     // 上のコードをもう少しわかりやすく書くと、このようになります。
>     echo ((true ? 'true' : false) ? 't' : 'f');

>     // まず、最初の式が 'true' と評価されます。この 'true' は
>     // (bool) true と評価されるので、それをもとに二番目の三項
>     // 演算子が評価されます。
>     ?>

> 注意:

> 一方で、三項演算子の短縮形の挙動は安定しており、 理にかなった動作をします。 これは、`false` と評価されない最初の引数を評価します。 但し、未定義の値については未だ警告が出るので注意して下さい。

> 例6 三項演算子の短縮形

>     <?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 合体演算子) を使うことが出来ます。

例7 デフォルト値の代入

    <?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 合体演算子はネストさせることもできます。

> 例8 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"` から取得できます。 この関数の結果はエラーごとに変わります。よって速やかに確認する必要があります。

例1 意図的なエラー

    <?php
    $my_file = @file ('non_existent_file') or
        die ("Failed opening file: error was '" . error_get_last()['message'] . "'");
    ?>

例2 式でのエラー抑制

    <?php
    // この演算子は関数だけでなく、全ての式で動作します。
    $value = @$cache[$key];
    // インデックス $key が存在しない場合でも、警告を発生しません。
    ?>

> 注意: `@` 演算子は、 式 に対してのみ動作します。基本的なルールは次のようになります。 値を得ることができるものの場合、 `@` 演算子を前に付けることが可能です。 例えば、変数、関数、いくつかの言語構造(例: include) のコールなどの前に、この演算子をつけることが可能です。 関数またはクラスの定義、 `if` や `foreach` 等のような 条件構造の前には、この演算子を付けることはできません。

警告

PHP 8.0.0 より前のバージョンでは、 スクリプトの実行を停止させるような致命的な場合であっても `@` 演算子でエラーメッセージを抑止することが可能でした。 たとえば、存在しなかったり、ミスタイプされていたり、 利用できない関数コールの前に `@` 演算子を付けると、 原因を示すことなく、その場所でスクリプトは終了してしまっていました。

### 参考

- error_reporting()
- エラーハンドリングとロギング関数

## 実行演算子

PHP は 1 種類の実行演算子、バッククォート (````) をサポートします。 シングルクォートではないことに注意してください! PHP は、バッククォートの 中身をシェルコマンドとして実行しようとします。出力が返されます (すなわち、出力を単にダンプするのではなく、変数に代入することが できます) 。 バッククォート演算子の使用は shell_exec() と等価です。

例1 バッククォート演算子

    <?php
    $output = `ls -al`;
    echo "<pre>$output</pre>";
    ?>

> 注意:

> バッククォート演算子は、 shell_exec() が無効な場合は無効となります。

> 注意:

> 他の言語とは異なり、 ダブルクォートで囲まれた文字列の中でのバッククォート演算子には何の効力もありません。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | 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 番目は、結合代入演算子('`.=`')で、 この演算子は右側の引数に左側の引数を追加します。詳細は、代入演算子 を 参照ください。

例1 文字列結合

    <?php
    $a = "Hello ";
    $b = $a . "World!"; // $b は、"Hello World!" となります。
    var_dump($b);

    $a = "Hello ";
    $a .= "World!"; // $a は、"Hello World!" となります。
    var_dump($a);
    ?>

### 参考

- 文字列
- 文字列 関数

## 配列演算子

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`。

`+` 演算子は、右側の配列を左側の配列に追加したものを返します。 両方の配列に存在するキーについては左側の配列の要素が優先され、 右側の配列にあった同じキーの要素は無視されます。

例1 配列結合演算子

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

同じキーと値を保持している場合に、配列が等しいとみなされます。

例2 配列の比較

    <?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 = fopen('/tmp/', 'r');
    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()

## パイプ演算子

PHP 8.5 以降では、callable に直接値を渡す演算子をサポートしています。 `|>` 演算子、または "パイプ" は、右辺にパラメーターをひとつ取る callable を受け入れ、左辺値をそれに渡し、callable の結果を評価します。 右辺の callable は、有効な PHP の callable であれば何でも構いません: つまり、Closure、 第一級callableを生成する記法、 __invoke() を実装したオブジェクトなどです。

論理的には同じ意味になる、2行のコードを以下に示します。

例1 `|>` を使う

    <?php
    $result = "Hello World" |> strlen(...);
    echo $result, PHP_EOL;

    $result = strlen("Hello World");
    echo $result, PHP_EOL;
    ?>

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

    11
    11

単一の呼び出しは特に役に立ちませんが、 複数の呼び出しを一緒にチェインさせると役に立ちます。 たとえば、論理的には同じ意味になるコード片を2つ、以下に示します:

例2 |> の呼び出しをチェインさせる

    <?php
    $result = "PHP Rocks"
        |> htmlentities(...)
        |> str_split(...)
        |> (fn($x) => array_map(strtoupper(...), $x))
        |> (fn($x) => array_filter($x, fn($v) => $v != 'O'))
    ;
    print_r($result);

    $temp = "PHP Rocks";
    $temp = htmlentities($temp);
    $temp = str_split($temp);
    $temp = array_map(strtoupper(...), $temp);
    $temp = array_filter($temp, fn($v) => $v != 'O');
    $result = $temp;
    print_r($result);
    ?>

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

    Array
    (
        [0] => P
        [1] => H
        [2] => P
        [3] =>
        [4] => R
        [6] => C
        [7] => K
        [8] => S
    )
    Array
    (
        [0] => P
        [1] => H
        [2] => P
        [3] =>
        [4] => R
        [6] => C
        [7] => K
        [8] => S
    )

パイプの左側は、値や式であれば何でも構いません。 パイプの右側は、パラメーターをひとつ取る PHP の有効な callable か、 そのように評価できる任意の式であれば何でも構いません。 必須のパラメーターをひとつ以上とる関数を右側に指定した場合、 それは許可されず、 引数が不足した状態で関数をコールしたかのように失敗します。 リファレンスの値を取る関数も許可されていません。 右辺が有効な callable として評価されない場合、Error がスローされます。

> 注意:

> 上の例で示したとおり、文法的な曖昧さを回避するため、 アロー関数 は、 パイプ演算子と一緒に使う場合に括弧で囲わなければならない点に注意してください。 そうしない場合、致命的なエラーが発生します。

### 参考

- Closure

# 制御構造

## 目次

- はじめに
- 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;

    <?php
    /* 正しい方法 */
    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` は、 配列と Traversable オブジェクトを反復処理する簡単な方法を提供します。 それらと異なるデータ型や、未初期化の変数と一緒に `foreach` を使うと、エラーが発生します。

`foreach` は、オプションで以下のようにして要素ごとの `key` も取得できます。

    foreach (iterable_expression as $value) {
        statement_list
    }

    foreach (iterable_expression as $key => $value) {
        statement_list
    }

最初の形式は、`iterable_expression` で指定した反復可能な値に 関してループ処理を行います。各反復において現在の要素の値が `$value`に代入されます。

2番目の形式は、さらに各反復で現在の要素のキーを変数 `$key`に代入します。

`foreach` は、 current() や key() のような関数で使われる、内部的な配列のポインタを変更しない点に注意して下さい。

オブジェクトの反復処理をカスタマイズ することもできます。

例1 一般的な `foreach` の使用法

    <?php

    /* 例: 値のみ */
    $array = [1, 2, 3, 17];

    foreach ($array as $value) {
        echo "Current element of \$array: $value.\n";
    }

    /* 例: キーと値 */
    $array = [
        "one" => 1,
        "two" => 2,
        "three" => 3,
        "seventeen" => 17
    ];

    foreach ($array as $key => $value) {
        echo "Key: $key => Value: $value\n";
    }

    /* 例: 多次元のキーと値の配列 */
    $grid = [];
    $grid[0][0] = "a";
    $grid[0][1] = "b";
    $grid[1][0] = "y";
    $grid[1][1] = "z";

    foreach ($grid as $y => $row) {
        foreach ($row as $x => $value) {
            echo "Value at position x=$x and y=$y: $value\n";
        }
    }

    /* Example: dynamic arrays */
    foreach (range(1, 5) as $value) {
        echo "$value\n";
    }
    ?>

> 注意:

> `foreach` は、 `@` を使ってエラーメッセージを抑制する機能はサポートしていません。

### ネストした配列のアンパック

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

配列の配列を反復処理し、 ネストした配列をループ変数に展開させることができます。 配列の分解 を `[]` で行うか、list() 言語構造を反復処理の値として指定します。

> 注意: `[]` による 配列の分解 処理は、PHP 7.1.0 以降でのみ利用可能である点に注意しましょう。

以下の例は両方、 `$a` にネストされた配列の最初の要素が設定され、 `$b` には二番目の要素が含まれます:

    <?php
    $array = [
        [1, 2],
        [3, 4],
    ];

    foreach ($array as [$a, $b]) {
        echo "A: $a; B: $b\n";
    }

    foreach ($array as list($a, $b)) {
        echo "A: $a; B: $b\n";
    }
    ?>

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

    A: 1; B: 2
    A: 3; B: 4

配列の要素より少ない変数が指定された場合、 残りの要素は無視されます。 同様に、以下のようにしてカンマを使うことで要素をスキップできます:

    <?php
    $array = [
        [1, 2, 5],
        [3, 4, 6],
    ];

    foreach ($array as [$a, $b]) {
        // Note that there is no $c here.
        echo "$a $b\n";
    }

    foreach ($array as [, , $c]) {
        // Skipping over $a and $b
        echo "$c\n";
    }
    ?>

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

    1 2
    3 4
    5
    6

以下のように、list() を埋めるだけの十分な要素数が配列にない場合、警告が発生します:

    <?php
    $array = [
        [1, 2],
        [3, 4],
    ];

    foreach ($array as [$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:

### foreach とリファレンス

ループ中で、 `$value` の前に `&` をつけることで、配列の要素を直接変更することができます。 この場合、値は リファレンス として代入されます。

    <?php
    $arr = [1, 2, 3, 4];
    foreach ($arr as &$value) {
        $value = $value * 2;
    }
    // $arr is now [2, 4, 6, 8]
    unset($value); // break the reference with the last element
    ?>

警告

配列の最後の要素の `$value` へのリファレンスは、 `foreach` が終了した後も残ったままです。 このリファレンスは unset() することをお勧めします。 そうしないと、以下のようなことが起きてしまいます:

    <?php
    $arr = [1, 2, 3, 4];
    foreach ($arr as &$value) {
        $value = $value * 2;
    }
    // $arr は現在 [2, 4, 6, 8]

    // unset($value) しないと、$value はまだ最後の要素 $arr[3] を指した状態のままです

    foreach ($arr as $key => $value) {
        // $arr[3] は $arr の値ごとに更新され続けてしまいます...
        echo "{$key} => {$value} ";
        print_r($arr);
    }
    // ...最終的に、最後から2番目の値が最後の値にコピーされるまで
    ?>

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

    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 )

例2 定数の配列の値を、リファレンスで反復処理する

    <?php
    foreach ([1, 2, 3, 4] as &$value) {
        $value = $value * 2;
    }
    ?>

### 参考

- array
- Traversable
- iterable
- list()

## 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 >= 40 => "Adult",
        $age > 19 => "Young adult",
    };

    var_dump($output);
    ?>

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

    string(8) "Teenager"

> 注意: `match` 式の結果は、必ずしも使う必要はありません。

> 注意: `match` 式を単一の式として使う場合は、必ずセミコロン `;` で終わらなければなりません。

`match` 式は、 `switch` 文と似ていますが、いくつかの違いがあります:

- `match` 式の比較は、 switch 文が行う弱い比較ではなく、 厳密に値を比較(`===`) します。
- `match` 式は値を返します。
- `match` 式の分岐は、 `switch` 文のように後の分岐に抜けたりはしません。
- `match` 式は、全ての場合を網羅していなければいけません。

`switch` 文のように、 `match` 式はマッチさせる分岐をひとつひとつ実行します。 はじめは、コードは何も実行されません。 以前のすべての条件式が、制約式とマッチしなかった場合に条件式が実行されます。 条件式に一致する式が評価された場合に、返却式が評価されます。 たとえば、以下のようになります:

    <?php
    $result = match ($x) {
        foo() => 'value',
        $this->bar() => 'value', // 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`ブロックの挙動を指定することが出来ます。 現在のところ、使用できるディレクティブは以下の3つだけです:

- `ticks`
- `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 とほぼ同じですが、失敗した場合に Error も発生する点が異なります(PHP 8.0.0 より前のバージョンでは、 `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)

この画像は » 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を生成する記法

## ユーザー定義関数

関数は、`function` キーワードと関数の名前、 カンマ(`,`) で区切ったパラメーターのリスト （空であっても構いません）を括弧で囲み、 関数の本体を波括弧で囲んだものを続けて定義します。 たとえば、以下のようになります:

例1 `foo` という名前の新しい関数を宣言する

    <?php
    function foo($arg_1, $arg_2, /* ..., */ $arg_n)
    {
        echo "関数の例\n";
        return $retval;
    }

> 注意:

> PHP 8.0.0 以降では、 パラメーターのリストの末尾に、カンマを付加できるようになっています:

>     <?php
>     function foo($arg_1, $arg_2,) { }

関数の本体の中では、 他の関数や クラス 定義を含む PHP のあらゆる有効なコードを使用することができます。

関数名は、PHP の他のラベルと同じ規則に従います。関数名として有効な 形式は、まず文字かアンダースコアで始まり、その後に任意の数の文字・ 数字・あるいはアンダースコアが続くものです。正規表現で表すと、 `^[a-zA-Z_\x80-\xff][a-zA-Z0-9_\x80-\xff]*$` となります。

ヒント

ユーザーレベルでの命名の手引き も参照ください。

PHP では、関数は参照される前に定義されている必要はありません。 ただし以下の二つの例のように、条件付きで関数が 定義されるような場合を除きます。

次の二つの例のように、ある条件下でのみ関数が定義される場合には、 その関数定義は関数がコールされる前に 行われていなければなりません。

例2 条件つきの関数

    <?php
    $makefoo = true;

    /* ここでは関数foo()はまだ定義されていないので
       コールすることはできません。
       しかし関数 bar()はコールできます。 */
    if (function_exists('foo')) {
        foo();
    } else {
        echo "Function foo does not exist (yet).\n";
    }

    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()はまだ定義されていないので
       コールすることはできません。 */
    if (function_exists('bar')) {
        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);
        }
    }

    recursion(17);

> 注意: 100 から 200 を超えるようなレベルの再帰呼び出しは避けてください。そんなことをすると、 スタックが破壊され、スクリプトが異常終了してしまいます。 無限に続くような再帰処理は、プログラミングの間違いでしょう。

## 関数のパラメーターと引数

関数のパラメーターは、関数のシグネチャの中で宣言します。 引数のリストにより関数へ情報を渡すことができます。 このリストは、カンマで区切られた式のリストです。 引数の評価は、関数が実際にコールされる前に、 左から右の順番で行われ、 評価された結果が関数のパラメーターに代入されます (先行評価)。

PHP は、値渡し(デフォルト)、 リファレンス渡し、 デフォルト引数値 をサポートしています。また、 可変長引数リスト や、 名前付き引数 もサポートしています。

> 注意:

> PHP 7.3.0 以降では、 関数コールの引数リストの末尾にも、カンマを付加できるようになっています:

>     <?php
>     $v = foo(
>         $arg_1,
>         $arg_2,
>     );

PHP 8.0.0 以降では、関数のパラメーターリストの最後にカンマをつけることができます。 このカンマは無視されます。 これは、パラメータリストや変数名が長かったりした場合に、 パラメータを縦に並べるのに便利です。

例1 関数のパラメーターリストの最後にカンマを付ける

    <?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 より前では許されません。
    )
    {
        // ...
    }

### 引数のリファレンス渡し

デフォルトで、関数の引数は値で渡されます。(このため、関数の内部で 引数の値を変更しても関数の外側では値は変化しません。)関数がその引 数を修正できるようにするには、その引数をリファレンス渡しとする必要があり ます。

関数の引数を常にリファレンス渡しとしたい場合には、関数定義において アンパサンド(&) をパラメーター名の前に付加することができます。

例2 関数の引数のリファレンス渡し

    <?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` を渡した場合はデフォルト値を代入 しない ことに特に注意して下さい。

例3 関数におけるデフォルトパラメータの使用法

    <?php
    function makecoffee($type = "cappuccino")
    {
        return "Making a cup of $type.\n";
    }
    echo makecoffee();
    echo makecoffee(null);
    echo makecoffee("espresso");

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

    Making a cup of cappuccino.
    Making a cup of .
    Making a cup of espresso.

デフォルトパラメータの値には、スカラー値、 配列、および特殊な型 `null` を指定できます。 PHP 8.1.0 以降では、 new ClassName() 記法を使ってオブジェクトも指定できます。

例4 スカラー型以外をデフォルト値として使用する

    <?php
    function makecoffee($types = array("cappuccino"), $coffeeMaker = NULL)
    {
        $device = is_null($coffeeMaker) ? "hands" : $coffeeMaker;
        return "Making a cup of ".join(", ", $types)." with $device.\n";
    }
    echo makecoffee();
    echo makecoffee(array("cappuccino", "lavazza"), "teapot");

例5 オブジェクトをデフォルト値として使用する(PHP 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);

デフォルト値は、定数式である必要があり、 (例えば) 変数やクラスのメンバーであってはなりません。

デフォルト値を有するパラメータは、 デフォルト値がないパラメータの右側に全てある必要があることに注意して下さい。 そうでない場合、デフォルト値を指定していても、 呼び出し時に省略できません。 次の簡単なコードを見てみましょう。

例6 関数のパラメーターのデフォルト値の 間違った使用法

    <?php
    function makeyogurt($container = "bowl", $flavour)
    {
        return "Making a $container of $flavour yogurt.\n";
    }

    echo makeyogurt("raspberry"); // $container に "raspberry" を指定します。$flavour ではありません。

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

    Deprecated: makeyogurt(): Optional parameter $container declared before required parameter $flavour is implicitly treated as a required parameter in script on line 2

    Fatal error: Uncaught ArgumentCountError: Too few arguments to function makeyogurt(), 1 passed in script on line 7 and exactly 2 expected in script:2
    Stack trace:
    #0 script(7): makeyogurt('raspberry')
    #1 {main}
      thrown in script on line 2

ここで、上の例を次のコードと比べてみましょう。

例7 関数のパラメーターのデフォルト値の 正しい使用法

    <?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 以降では、 デフォルト値を指定したパラメータを複数スキップするために、 名前付き引数 が使えます。

例8 関数のパラメータのデフォルト値の 正しい使用法

    <?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 であることを示しています。 この使い方はPHP 8.4.0で非推奨となり、代わりに明示的な nullable 型 を使用する必要があります。

例9 デフォルト値を指定したパラメーターは、必須のパラメーターの後に宣言する

    <?php
    function foo($a = [], $b) {} // デフォルト値が使われないため、PHP 8.0.0 以降は推奨されません
    function foo($a, $b) {}      // 上のコードと機能的には同じですが、推奨されない警告は発生しません。

    // PHP 8.1.0以降、$a は暗黙的に必須（必須のパラメータの前にあるため）ですが、
    // デフォルトのパラメータ値が null であるため、暗黙的に nullable とみなされます（PHP 8.4.0で非推奨）。
    function bar(A $a = null, $b) {}
    function bar(?A $a, $b) {}       // 推奨される書き方です。

> 注意: PHP 7.1.0 以降では、 デフォルト値を指定しないでパラメータを省略すると、 ArgumentCountError がスローされるようになりました。 これより前のバージョンでは、警告が発生していました。

> 注意: リファレンス渡しのパラメーターにもデフォルト値を指定できます。

### 可変長引数リスト

PHP は `...` を使った可変長引数をユーザー定義関数でサポートしています。

パラメーターリストに `...` トークンを含めることで、 その関数が可変長の引数を受け取ることを示せます。 引数は、指定した変数に配列として渡されます:

例10 `...` を使った、可変長引数へのアクセス

    <?php
    function sum(...$numbers) {
        $acc = 0;
        foreach ($numbers as $n) {
            $acc += $n;
        }
        return $acc;
    }

    echo sum(1, 2, 3, 4);

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

    10

関数を呼び出すときに `...` を使うと、 配列や Traversable を実装した変数やリテラルを引数リストに展開することができます。

例11 引数での `...` の使用例

    <?php
    function add($a, $b) {
        return $a + $b;
    }

    echo add(...[1, 2])."\n";

    $a = [1, 2];
    echo add(...$a);

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

    3
    3

通常のパラメーターを、`...` の前に指定することもできます。 この場合は、通常の引数リストにマッチしなかったのこりの引数が `...` による配列に追加されます。

`...` トークンの前に、 型宣言 を付加することもできます。 型宣言がある場合、`...` が取り込むすべての引数はその型に一致していなければいけません。

例12 型宣言つきの可変長引数

    <?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
    Fatal error: Uncaught TypeError: total_intervals(): Argument #2 must be of type DateInterval, null given, called in script on line 15 and defined in script:2
    Stack trace:
    #0 script(15): total_intervals('d', NULL)
    #1 {main}
      thrown in script on line 2

可変長引数の リファレンス渡し もできます。その場合は、`...` の前にアンパサンド (`&`) を付加します。

### 名前付き引数

既にある、位置を指定した引数を拡張する形で、PHP 8.0.0 から名前付き引数が導入されました。 名前付き引数は、位置ではなく、名前ベースで引数を渡すことを可能にします。 これによって、引数の意味が自己文書化(self-documenting)され、 引数を任意の順番で渡せるようになり、任意のデフォルト値を持つ引数をスキップできるようになります。

名前付き引数は、パラメータの名前の後にコロンを付けたものを、値の前に付けることで指定します。 パラメータの名前に予約語を使うことも許されています。 パラメータの名前は識別子でなければならず、動的に指定することは出来ません。

例13 名前付き引数の文法

    <?php
    myFunction(paramName: $value);
    array_foobar(array: $value);

    // 以下の書き方はサポートされていません
    function_name($variableStoringParamName: $value);

例14 位置を指定した引数と、名前付き引数

    <?php
    // 位置を指定した引数の場合:
    array_fill(0, 100, 50);

    // 名前付き引数の場合:
    array_fill(start_index: 0, count: 100, value: 50);

名前付き引数は、渡す順番は関係ありません。

例15 上と同じ例を、引数の順番を変えて渡す

    <?php
    array_fill(value: 50, count: 100, start_index: 0);

名前付き引数は、位置を指定した引数と組み合わせることが出来ます。 そうした場合、名前付き引数は、位置を指定した引数の後に置かなければいけません。 オプションの引数だけをいくつか、指定することもできます。 その場合も、名前付き引数の順番は関係ありません。

例16 位置を指定した引数と、名前付き引数を組み合わせる

    <?php
    htmlspecialchars($string, double_encode: false);
    // 上記は、以下と同等です。
    htmlspecialchars($string, ENT_QUOTES | ENT_SUBSTITUTE | ENT_HTML401, 'UTF-8', false);

同じ名前の引数を複数回渡すと、Error 例外が発生します。

例17 同じ名前の引数を複数回渡すと、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 以降では、 引数を ... で展開した後に 名前付き引数を指定することができます。 名前付き引数は、展開済みの引数を上書きしては いけません。

例18 引数を展開した後に、名前付き引数を使う

    <?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();
    var_dump($zero, $one, $two);

    // 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, unset(), isset(), empty(), include, require のような言語構造と組み合わせて使用する ことはできません。これらの言語構造を可変関数として使うには 独自のラッパー関数を使う必要があります。

例1 可変関数の例

    <?php
    function foo()
    {
        echo "In foo()\n";
    }

    function bar($arg = '')
    {
        echo "In bar(); argument was '$arg'.\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\n";
        }
    }

    echo Foo::$variable ."\n"; // これは 'static property' を表示します。このスコープにおいて $variable が必要です。
    $variable = "Variable";
    Foo::$variable();  // これは $foo->Variable() をコールします。このスコープでの $variable の内容を読むからです。

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

    static property
    Method Variable called

例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()を使う場合もやはり MySQLiサポートを有効にして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();

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

    Fatal error: Uncaught Error: Using $this when not in object context in script:7
    Stack trace:
    #0 script(9): Foo::{closure:Foo::__construct():6}()
    #1 script(12): Foo->__construct()
    #2 {main}
      thrown in script on line 7

例7 static な無名関数へのオブジェクトのバインド

    <?php
    $func = static function() {
        // 関数の本体
    };
    $func = $func->bindTo(new stdClass);
    $func();

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

    Warning: Cannot bind an instance to a static closure, this will be an error in PHP 9 in script on line 5

    Fatal error: Uncaught Error: Value of type null is not callable in script:6
    Stack trace:
    #0 {main}
      thrown in script on line 6

### 変更履歴

バージョン | 説明
--- | ---
8.3.0 | マジックメソッド 経由で作られたクロージャも、名前付き引数を受け入れるようになりました。
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($x): 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 の外部から行われ、
    // アクセス権のチェックもこの時点から行われるためです。

    <?php
    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 の予約語 以外でラベルとして有効なあらゆる名前を使用することができます。 PHP 8.4.0 以降では、アンダースコア (`_`) 1文字のみのクラス名は非推奨となりました。 有効なクラス名は、先頭が文字あるいはアンダースコアで始まり、 その後に任意の数の文字/数字/アンダースコアが続くものです。 正規表現で表すと、 `^[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
    class SimpleClass {
    }

    $instance = new SimpleClass();
    var_dump($instance);

    // 変数を使うこともできます
    $className = 'SimpleClass';
    $instance = new $className(); // new SimpleClass()
    var_dump($instance);
    ?>

PHP 8.0.0 以降では、 `new` を任意の式と一緒に使う機能がサポートされました。 これによって、式が文字列を生成する場合に、 より複雑なインスタンス化を行えるようになります。 式は括弧で囲まなければいけません。

例4 任意の式を使ってインスタンスを生成する

以下の例では、 クラス名を生成する有効な任意の式を複数示します。 関数呼び出し、文字列連結、そして `::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) {
    }

クラスのコンテキストにおいては、 `new self` や `new parent` のようにして新しいオブジェクトを作成することができます。

作成済みのクラスのインスタンスを新たな変数に代入する場合、新しい変数は、 代入されたオブジェクトと同じインスタンスにアクセスします。 この動作は、インスタンスを関数に渡す場合も同様です。 作成済みのオブジェクトのコピーは、その クローンを作成 することにより作成可能です。

例5 オブジェクトの代入

    <?php
    class SimpleClass {
        public string $var;
    }

    $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"
    }

複数のやり方で、オブジェクトのインスタンスを作ることが出来ます:

例6 新しいオブジェクトの作成

    <?php

    class Test
    {
        public static function getNew()
        {
            return new static();
        }
    }

    class Child extends Test {}

    $obj1 = new Test(); // By the class name
    $obj2 = new $obj1(); // Through the variable containing an object
    var_dump($obj1 !== $obj2);

    $obj3 = Test::getNew(); // By the class method
    var_dump($obj3 instanceof Test);

    $obj4 = Child::getNew(); // Through a child class method
    var_dump($obj4 instanceof Child);

    ?>

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

    bool(true)
    bool(true)
    bool(true)

新しく作成したオブジェクトのメンバーに、作成したその式の中でもアクセスすることができます。

例7 新しく作成したオブジェクトのメンバーへのアクセス

    <?php
    echo (new DateTime())->format('Y'), PHP_EOL;

    // PHP 8.4.0 以降、囲む括弧は省略可能です。
    echo new DateTime()->format('Y'), PHP_EOL;
    ?>

上の例の出力は、 たとえば以下のようになります。

    2025
    2025

> 注意: 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 SimpleClass
    {
        function displayVar()
        {
            echo "Parent class\n";
        }
    }

    class ExtendClass extends SimpleClass
    {
        // 親クラスのメソッドを再定義
        function displayVar()
        {
            echo "Extending class\n";
            parent::displayVar();
        }
    }

    $extended = new ExtendClass();
    $extended->displayVar();
    ?>

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

    Extending class
    Parent Class

#### シグネチャの互換性に関するルール

メソッドをオーバーライドするときは、 子クラスのシグネチャが親クラスのそれと互換性がなければいけません。 互換性が壊れた場合、致命的なエラーが発生します。 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` を付けてプロパティを宣言できます。これによって、プロパティを初期化した後に値が変更されることを防止できます。 PHP 8.4.0 より前のバージョンでは、`readonly` プロパティは暗黙的に private-set であり、 同じクラス内からのみ書き込みが可能でした。 PHP 8.4.0 以降では、`readonly` プロパティは暗黙的に `protected(set)` となり、 子クラスからも設定可能です。必要に応じて明示的に オーバーライドすることもできます。

例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;
    unset($test->ary[0]);
    $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 8.3.0 以降では、 読み取り専用プロパティは __clone() を使ったオブジェクトのクローン時に再初期化できるようになりました。

例6 読み取り専用プロパティとオブジェクトのクローン

    <?php
    class Test1 {
        public readonly ?string $prop;

        public function __clone() {
            $this->prop = null;
        }

        public function setProp(string $prop): void {
            $this->prop = $prop;
        }
    }

    $test1 = new Test1;
    $test1->setProp('foobar');

    $test2 = clone $test1;
    var_dump($test2->prop); // NULL
    ?>

### 動的なプロパティ

オブジェクトに対して、存在しないプロパティを代入しようとした場合、 PHP は自動的に対応するプロパティを作成します。 こうして作成された動的なプロパティは、 そのインスタンスで のみ 使えます。

警告

動的なプロパティは、PHP 8.2.0 以降は推奨されなくなりました。 代わりに、プロパティを宣言することを推奨します。 任意のプロパティの名前を扱うには、 クラスがマジックメソッド __get() と __set() を実装すべきです。 動的なプロパティを使うための最終手段として、 アトリビュート `#[\AllowDynamicProperties]` でクラスをマークすることができます。

## プロパティフック

プロパティフックは、他の言語では「プロパティアクセサー」とも呼ばれる仕組みで、 プロパティの読み書き動作へ干渉し、それを上書きする機能を提供します。 この機能には、次の2つの目的があります:

1. get- メソッドや set- メソッドを使わずプロパティを参照しつつ、 将来的に追加の機能を追加する余地を残す。 フックを使わない場合の定型の get/set メソッドのほとんどは 不要になる。
2. 実際に値を保持することなく、 オブジェクトを説明するプロパティを実装する。

static でないプロパティには `get` と `set` の2種類のフックがあります。 それぞれ、プロパティの読み取りと書き込みの動作を上書きします。 フックは、型付きプロパティ、型のないプロパティ、いずれにも利用可能です。

プロパティはバックドプロパティか仮想プロパティのどちらかになります。 バックドプロパティは実体の値を持つプロパティです。 フックを持たないプロパティは、全てバックドプロパティになります。 仮想プロパティは、実体の値を必要としないフックだけを持つプロパティです。 この場合、フックは実質的にメソッドと等価であり、 オブジェクトはこのプロパティ用のメモリを必要としません。

プロパティフックは `readonly` プロパティと同時に使えません。 `get` や `set` の動作の変更だけでなく アクセス自体の制限も行いたい場合、 非対称可視性プロパティ を使ってください。

> 注意: バージョン情報
> プロパティフックは PHP 8.4 で導入されました。

### 基本的なフック構文

フックを宣言する一般的な構文は次のとおりです。

例1 プロパティフック (フルバージョン)

    <?php
    class Example
    {
        private bool $modified = false;

        public string $foo = 'default value' {
            get {
                if ($this->modified) {
                    return $this->foo . ' (modified)';
                }
                return $this->foo;
            }
            set(string $value) {
                $this->foo = strtolower($value);
                $this->modified = true;
            }
        }
    }

    $example = new Example();
    $example->foo = 'changed';
    print $example->foo;
    ?>

$foo プロパティの末尾はセミコロンではなく `{}` です。 これがフックの存在を表します。 ここでは `get` と `set` 両方のフックを定義していますが、 一方だけ定義することも可能です。 どちらのフックも `{}` の中に任意のコードを書くことができます。

`set` フックは、渡される値の型と名前を メソッドと同じ書式で指定できます。 この型はプロパティの型と同じか、 反変 (より広い型) でなければなりません。 たとえば string 型のプロパティに対しては、 string|Stringable を受け取る `set` フックを定義できますが、 array のみを受け取るものは定義できません。

少なくとも一方のフックが `$this->foo`（プロパティ自体）を参照しているため、 このプロパティはバックドプロパティになります。 `$example->foo = 'changed'` が呼び出されると、 渡された文字列は小文字に変換され、それが値として保存されます。 プロパティを読み取る際には、保存された値に対し、条件に応じて追加の文字列が 付与されます。

よくあるケースに対応するために、いくつかの短縮構文が用意されています。

`get` フックが単独の式である場合、 `{}` を省略してアロー式で置き換えることができます。

例2 プロパティの get 式

この例は前の例と等価です。

    <?php
    class Example
    {
        private bool $modified = false;

        public string $foo = 'default value' {
            get => $this->foo . ($this->modified ? ' (modified)' : '');

            set(string $value) {
                $this->foo = strtolower($value);
                $this->modified = true;
            }
        }
    }
    ?>

`set` フックのパラメータの型がプロパティの型と同じ場合 (典型的にはそうなります)、 その型は省略可能です。この場合、渡される値には自動的に $value という名前が付きます。

例3 プロパティ set のデフォルト

この例は前の例と等価です。

    <?php
    class Example
    {
        private bool $modified = false;

        public string $foo = 'default value' {
            get => $this->foo . ($this->modified ? ' (modified)' : '');

            set {
                $this->foo = strtolower($value);
                $this->modified = true;
            }
        }
    }
    ?>

`set` フックが、渡された値を変形して保存するだけの場合には、 アロー式でより簡略にできます。 式の評価結果が値として保存されます。

例4 プロパティの set 式

    <?php
    class Example
    {
        private bool $modified = false;

        public string $foo = 'default value' {
            get => $this->foo . ($this->modified ? ' (modified)' : '');
            set => strtolower($value);
        }
    }
    ?>

この例は `$this->modified` の値を更新していないため 前の例と等価ではありません。 set フック内で複数の文が必要な場合、中括弧付きの構文を使用してください。

プロパティは状況に応じて、一方または双方のフックを実装するか、どちらも実装しないことができます。 それぞれの短縮構文は独立しており、 たとえば「短縮構文の get と 通常の set」 「型を明示した短縮構文の set」など、いずれも有効です。

バックドプロパティで `get` や `set` のフックを省略した場合、 それはデフォルトの読み書き動作になります。

> 注意: フックは コンストラクタのプロモーション にも定義できます。ただし、コンストラクタで受け取る値は `set` フックが受け入れる型ではなく、 プロパティの本来の型に一致しなければならない点に注意してください。 次のような例を考えます:

>     <?php
>     class Example
>     {
>         public function __construct(
>             public private(set) DateTimeInterface $created {
>                 set (string|DateTimeInterface $value) {
>                     if (is_string($value)) {
>                         $value = new DateTimeImmutable($value);
>                     }
>                     $this->created = $value;
>                 }
>             },
>         ) {
>         }
>     }

> 内部では次のような形で処理されます:

>     <?php
>     class Example
>     {
>         public private(set) DateTimeInterface $created {
>             set (string|DateTimeInterface $value) {
>                 if (is_string($value)) {
>                     $value = new DateTimeImmutable($value);
>                 }
>                 $this->created = $value;
>             }
>         }

>         public function __construct(
>             DateTimeInterface $created,
>         ) {
>             $this->created = $created;
>         }
>     }

> コンストラクタ以外からプロパティに値を書き込む時は string か DateTimeInterface を受け入れますが、 コンストラクタからは DateTimeInterface のみ受け入れます。 プロパティの型 (DateTimeInterface) が コンストラクタのシグネチャのパラメータ型として使われ、 `set` フックが受け入れる型は参照されないためです。 このような振る舞いがコンストラクタでも必要な場合、 コンストラクタのプロモーションは使用できません。

### 仮想プロパティ

仮想プロパティは、値を保持しないプロパティです。 `get`、`set` いずれのフックも プロパティ自体を正確に参照していない場合、それは仮想プロパティになります。 例えば、`$foo` という名前のプロパティのフックに `$this->foo` というコードが含まれれば、それはバックドプロパティです。 次のプロパティはバックドプロパティではなく、エラーが発生します:

例5 無効な仮想プロパティ

    <?php
    class Example
    {
        public string $foo {
            get {
                $temp = __PROPERTY__;
                return $this->$temp; // $this->foo を正確に参照していません
            }
        }
    }
    ?>

仮想プロパティでは、フックを省略するとその操作は存在しないとみなされ、 使おうとするとエラーが発生します。 仮想プロパティはオブジェクト内でメモリを消費しません。 仮想プロパティは、例えば他の2つのプロパティを組み合わせて値を作るような 「派生」プロパティに向いています。

例6 仮想プロパティ

    <?php
    class Rectangle
    {
        // 仮想プロパティ
        public int $area {
            get => $this->h * $this->w;
        }

        public function __construct(public int $h, public int $w) {}
    }

    $s = new Rectangle(4, 5);
    print $s->area; // 20 と表示
    $s->area = 30; // set が定義されていないためエラー
    ?>

仮想プロパティに対して `get` と `set` 両方のフックを定義することもできます。

### スコープ

全てのフックは、オブジェクトスコープで動作します。 すなわち、全ての public、private、protected な メソッドやプロパティに対してアクセスできます。 フックを持つプロパティへアクセスする場合も同様です。 フック内で別のプロパティにアクセスしても、そのフックがバイパスされることはありません。

重要なのは、フック内で必要に応じて、 任意の複雑なメソッドを呼び出すこともできるという点です。

例7 フックからメソッド呼び出し

    <?php
    class Person {
        public string $phone {
            set => $this->sanitizePhone($value);
        }

        private function sanitizePhone(string $value): string {
            $value = ltrim($value, '+');
            $value = ltrim($value, '1');

            if (!preg_match('/\d\d\d\-\d\d\d\-\d\d\d\d/', $value)) {
                throw new \InvalidArgumentException();
            }
            return $value;
        }
    }
    ?>

### リファレンス

フックはプロパティの読み書きの操作へ干渉するため、 プロパティへのリファレンスを取得したり、 `$this->arrayProp['key'] = 'value';` のような 間接的な変更操作を行う場合に問題が発生します。 リファレンスによる値の変更が set フックをバイパスしてしまうからです。

プロパティからフックを経由してリファレンスを取得する必要がある場合、 `get` フックの先頭に `&` を付与します。 同じプロパティで `get` と `&get` を両方定義すると 構文エラーになります。

バックドプロパティでは `&get` フックと `set` フックは同時に定義できません。 前述のとおり、リファレンスへの書き込みは `set` フックをバイパスしてしまうためです。 仮想プロパティでは、両フックから共有される実体の値がないため、同時に定義しても問題ありません。

配列プロパティのインデックスへ書き込みを行う場合も、暗黙的にリファレンスが使われます。 従って、フックを伴う配列のバックドプロパティの要素の書き換えができるのは、 `&get` フックだけが定義されている場合に限ります。 仮想プロパティの場合、 `get` や `&get` から返された配列の書き換え自体は可能ですが、 それが実際にオブジェクトに反映されるかはフックの実装次第です。

配列全体を上書きする場合は問題ありません。他のプロパティと同様に扱われます。 配列の個々の要素を操作する場合のみ注意が必要です。

### 継承

#### final フック

フックは final としても宣言することもできます。 その場合はオーバーライドできなくなります。

例8 final フックの例

    <?php
    class User
    {
        public string $username {
            final set => strtolower($value);
        }
    }

    class Manager extends User
    {
        public string $username {
            // これは許可される
            get => strtoupper($this->username);

            // parentのsetがfinalのため許可されない。
            set => strtoupper($value);
        }
    }
    ?>

プロパティ自体を final と宣言することもできます。 final で宣言されたプロパティは子クラスで再宣言できず、 フックを変更したりアクセス権を広げることもできません。

final と宣言したプロパティに対しフックも final とするのは 単に冗長であり無視されます。 これは final メソッドと同じ動作です。

子クラスでは、オーバーライドしたいフックを再定義することで、 フックを個別にオーバーライドできます。 フックを持たないプロパティにフックを追加することもできます。 フックがメソッドのように振る舞うという点で、一貫した動作です。

例9 フックの継承

    <?php
    class Point
    {
        public int $x;
        public int $y;
    }

    class PositivePoint extends Point
    {
        public int $x {
            set {
                if ($value < 0) {
                    throw new \InvalidArgumentException('Too small');
                }
                $this->x = $value;
            }
        }
    }
    ?>

それぞれのフックは親の実装を個別にオーバーライドします。 子クラスがフックを追加する場合、親クラスのプロパティで設定されたデフォルト値は削除され、再宣言が必要です。 これはフックのないプロパティを継承する場合と同じ動作です。

#### 親フックへのアクセス

子クラスのフックから `parent::$prop` に続き目的のフックを指定することで、 親クラスのプロパティにアクセスできます。 例えば `parent::$propName::get()` は、 「親クラスに定義された prop の get 操作を実行する」 という意味になります。同様に set 操作も実行できます。

これらの方法でアクセスしない限り、親クラスのフックは無視されます。 これはメソッドの動作と同じです。 この方法で親クラスの記憶領域にアクセスできます。 親クラスのプロパティにフックが存在しない場合、 デフォルトの get/set 動作が使われます。 フックは、自分自身のプロパティにおける親フック以外は呼び出せません。

上記の例は以下のように書き換えることができます。このようにすると、 将来 `Point` クラスに独自の `set` フックを追加しても問題になりません（前述の例では、 親クラスに追加されたフックが子クラスで無視されてしまいます）。

例10 親フックへのアクセス (set)

    <?php
    class Point
    {
        public int $x;
        public int $y;
    }

    class PositivePoint extends Point
    {
        public int $x {
            set {
                if ($value < 0) {
                    throw new \InvalidArgumentException('Too small');
                }
                parent::$x::set($value);
            }
        }
    }
    ?>

get フックだけをオーバーライドする場合、次の例のようになります:

例11 親フックへのアクセス (get)

    <?php
    class Strings
    {
        public string $val;
    }

    class CaseFoldingStrings extends Strings
    {
        public bool $uppercase = true;

        public string $val {
            get => $this->uppercase
                ? strtoupper(parent::$val::get())
                : strtolower(parent::$val::get());
        }
    }
    ?>

### シリアライズ

PHP には、オブジェクトを外部で利用したり デバッグしたりするための、いくつかのシリアライズ手段があります。 その際のフックの挙動は、用途によって異なります。 あるケースでは、プロパティに保存された生の値が使われ、 フックはバイパスされます。 別のケースでは、通常の読み書きと同じように フックを通して処理されます。

- var_dump(): 生の値を使用
- serialize(): 生の値を使用
- unserialize(): 生の値を使用
- __serialize()/__unserialize(): カスタムロジックと get/set フック
- 配列キャスト: 生の値を使用
- var_export(): get フックを使用
- json_encode(): get フックを使用
- JsonSerializable: カスタムロジックと get フック
- get_object_vars(): get フックを使用
- get_mangled_object_vars(): 生の値を使用

## クラス定数

値が変更できない 定数 をクラス内に定義することができます。 クラス定数のデフォルトのアクセス範囲は `public` です。

> 注意:

> クラス定数は、子クラスで再定義することもできます。 PHP 8.1.0 以降では、final として定義されたクラス定数は、子クラスで再定義できません。

インターフェイスに定数を持たせることもできます。 インターフェイスについてのドキュメント で例を御覧ください。

変数を用いてクラスを参照することも可能です。 変数の値に (`self` や `parent`、 `static` といった) キーワードを指定することはできません。

クラス定数はクラス単位で割り当てられるものです。インスタンス単位ではないことに注意しましょう。

PHP 8.3.0 以降では、クラス定数は `bool`, `int`, `float`, `string`, `array` のようなスカラー型を持つことができます。 `array` を使う場合、その内容は他のスカラー型に限ります。

例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 以降は、クラス定数のアクセス範囲を指定できるようになりました。

例5 PHP 8.3.0 以降で行われる、クラス定数のアクセス権の関係チェック

    <?php

    interface MyInterface
    {
        public const VALUE = 42;
    }

    class MyClass implements MyInterface
    {
        protected const VALUE = 42;
    }
    ?>

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

    Fatal error: Access level to MyClass::VALUE must be public (as in interface MyInterface) …

> 注意: PHP 8.3.0 以降では、アクセス権の関係がより厳密にチェックされるようになりました。 これより前のバージョンでは、 クラス定数のアクセス権は、インターフェイスを実装した側の定数のそれと異なっていても問題ありませんでした。

例6 PHP 8.3.0 以降で有効な、クラス定数を取得する文法

    <?php
    class Foo {
        public const BAR = 'bar';
        private const BAZ = 'baz';
    }

    $name = 'BAR';
    echo Foo::{$name}, PHP_EOL; // bar
    ?>

> 注意:

> PHP 8.3.0 以降では、クラス定数は変数を使って動的に取得できます。

例7 PHP 8.3.0 以降で有効な、クラス定数の型付け

    <?php

    class MyClass {
        public const bool MY_BOOL = true;
        public const int MY_INT = 1;
        public const float MY_FLOAT = 1.01;
        public const string MY_STRING = 'one';
        public const array MY_ARRAY = [self::MY_BOOL, self::MY_INT, self::MY_FLOAT, self::MY_STRING];
    }

    var_dump(MyClass::MY_BOOL);
    var_dump(MyClass::MY_INT);
    var_dump(MyClass::MY_FLOAT);
    var_dump(MyClass::MY_STRING);
    var_dump(MyClass::MY_ARRAY);
    ?>

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

    bool(true)
    int(1)
    float(1.01)
    string(3) "one"
    array(4) {
      [0]=>
      bool(true)
      [1]=>
      int(1)
      [2]=>
      float(1.01)
      [3]=>
      string(3) "one"
    }

## クラスのオートローディング

オブジェクト指向アプリケーションを作成する開発者の多くは、 クラス定義毎に一つの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 ...
    */
    ?>

例3 Composerのオートローダーの利用

» Composer は `vendor/autoload.php` ファイルを生成します。 これは Composer によって管理されているパッケージを自動的に読み込むよう設定されています。 このファイルを読み込むことで、これらのパッケージを追加の作業なしで利用できるようになります。

    <?php
    require __DIR__ . '/vendor/autoload.php';

    $uuid = new Ramsey\Uuid\Uuid::uuid7();

    echo "Generated new UUID -> ", $uuid->toString(), "\n";
    ?>

### 参考

- unserialize()
- unserialize_callback_func
- unserialize_max_depth
- spl_autoload_register()
- spl_autoload()
- __autoload()

## コンストラクタとデストラクタ

### コンストラクタ

function __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
    $some_json_string = '{ "id": 1004, "name": "Elephpant" }';
    $some_xml_string = "<animal><id>1005</id><name>Elephpant</name></animal>";

    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 {
            $data = simplexml_load_string($xml);
            $new = new static();
            $new->id = (int) $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);

    var_dump($p1, $p2, $p3);

コンストラクタは外部から呼ばれることを防ぐため、private または protected にしておきます。 この場合、staticメソッドだけがクラスをインスタンス化するのに使えます。 なぜなら、staticメソッドは、同じオブジェクトのインスタンスでなくとも、 private なメソッドにアクセスできる同じクラスのメソッド定義として存在するからです。 コンストラクタを private にすることはオプションです。使い方によっては意味がないかもしれません...

上の public なstaticメソッドは、オブジェクトをインスタンス化する3つの異なるやり方を示しています。

- `fromBasicData()` は、必要となる必須のパラメータを取り、 コンストラクタを呼ぶことでオブジェクトを生成し、その結果を返します。
- `fromJson()` は、JSON文字列を受け取り、 コンストラクタで必要なフォーマットに変換するための前処理を行います。 その上で、新しいオブジェクトを返します。
- `fromXml()` は、XML文字列を受け取り、前処理をします。 そして生のオブジェクトを生成します。コンストラクタは呼び出されていますが、 全てのパラメータはオプションなので、その実行はスキップされます。 結果を返す前に、オブジェクトのプロパティに直接値を代入しています。

上の3つの場合全てで、`static` キーワードはコードが存在するクラスの名前として解釈されます。 この場合は `Product` です。

### デストラクタ

function __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 8.4.0 以降、 ガベージサイクルの収集 が ファイバーの実行中に発生した場合、 回収がスケジュールされたオブジェクトのデストラクタは、 `gc_destructor_fiber`と呼ばれる 別のファイバー内で実行されます。 このファイバーが中断された場合、残りのデストラクタを実行するために新しいファイバーが作成されます。 中断された `gc_destructor_fiber` はガベージコレクタによって参照されなくなり、 他の参照がなければ回収される可能性があります。 デストラクタが中断されたオブジェクトは、デストラクタが復帰するかファイバー自体が回収されるまで回収されません。

> 注意:

> デストラクタの中から (スクリプトの終了処理時に) 例外をスローしようとすると、致命的なエラーを引き起こします。

## アクセス権

プロパティ、メソッドまたは (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 を表示します

    ?>

#### 非対称可視性プロパティ

PHP 8.4 から、オブジェクトのプロパティは非対称に アクセス権を設定できるようになりました。 読み取り(`get`)と書き込み(`set`)に 異なるスコープを設定できます。具体的には、`set` のアクセス権が メインのアクセス権より広くならない限り、 別々に指定できます。

例2 非対称可視性プロパティ

    <?php
    class Book
    {
        public function __construct(
            public private(set) string $title,
            public protected(set) string $author,
            protected private(set) int $pubYear,
        ) {}
    }

    class SpecialBook extends Book
    {
        public function update(string $author, int $year): void
        {
            $this->author = $author; // OK
            $this->pubYear = $year; // 致命的なエラー
        }
    }

    $b = new Book('How to PHP', 'Peter H. Peterson', 2024);

    echo $b->title; // OK
    echo $b->author; // OK
    echo $b->pubYear; // 致命的なエラー

    $b->title = 'How not to PHP'; // 致命的なエラー
    $b->author = 'Pedro H. Peterson'; // 致命的なエラー
    $b->pubYear = 2023; // 致命的なエラー
    ?>

PHP 8.5 以降では、 `set` はクラスの static プロパティにも適用できるようになりました。

例3 Asymmetric Static Property Visibility

    <?php
    class Manager
    {
        public private(set) static int $calls = 0;

        public function doAThing(): string
        {
            self::$calls++;
            // Do other stuff.
            return "some string";
        }
    }

    $m = new Manager();

    $m->doAThing(); // Works
    echo Manager::$calls; // Works
    Manager::$calls = 5; // Fatal error
    ?>

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

    1
    Fatal error: Uncaught Error: Cannot modify private(set) property Manager::$calls from global scope in /some/file.php

非対称可視性プロパティにはいくつかの注意点があります:

- 型付きプロパティのみが、`set` のアクセス権を個別に指定できます。
- `set` のアクセス権は、`get` と同じか、 より厳しくなければなりません。つまり、 `public protected(set)` および `protected protected(set)` は許可されますが、`protected public(set)` は構文エラーになります。
- プロパティが `public` の場合、メインのアクセス権は 省略できます。つまり、`public private(set)` と `private(set)` は 同じ結果になります。
- `private(set)` のアクセス権を持つプロパティは 自動的に `final` となり、子クラスで再宣言できません。
- プロパティへのリファレンスを取得する場合、`get` ではなく `set` のアクセス権に従います。 これは、リファレンスを使用してプロパティの値を変更できるためです。
- 同様に、配列プロパティへの書き込みを試みると、内部的には `get` と `set` の両方の操作が行われます。そのため、常により厳しい `set` のアクセス権に従います。

> 注意: アクセス権を set する宣言に、スペースは許されません。 `private(set)` は正しい宣言です。 `private( set )` は正しくないので、 パースエラーになります。

クラスが別のクラスを継承するとき、子クラスは `final` でない任意のプロパティを再定義できます。その際、 新しいアクセス権が親クラスと同じか広い場合に限り、 メインのアクセス権または `set` のアクセス権を広げることができます。ただし、 `private` プロパティがオーバーライドされると、 実際には親のプロパティを変更するのではなく、 異なる内部名を持つ新しいプロパティを作成することに注意してください。

例4 非対称可視性プロパティの継承

    <?php
    class Book
    {
        protected string $title;
        public protected(set) string $author;
        protected private(set) int $pubYear;
    }

    class SpecialBook extends Book
    {
        public protected(set) string $title; // OK。読み取りのアクセス権が広く、書き込みは同じだから。
        public string $author; // OK。読み取りのアクセス権は同じで、書き込みが広いから。
        public protected(set) int $pubYear; // 致命的なエラー。private(set) プロパティは final です。
    }
    ?>

### メソッドのアクセス権

クラスメソッドは、public, private, または protected として定義します。アクセス権を明示せずに宣言したメソッドは、 public となります。

例5 メソッドの宣言

    <?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 として定義されます。

例6 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 メンバーにアクセスすることができます。 これは、そのオブジェクトの内部ではオブジェクトの実装の詳細が既知であるからです。

例7 同じ型のオブジェクトの 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 MyClass {
        const CONST_VALUE = 'A constant value';
    }

    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 として定義されたメソッドは、そのメソッドのシグネチャと public または protected のアクセス権を宣言するのみで、 実装を定義することはできません。抽象プロパティは、 `get` や `set` の要件を宣言することができ、 実装はどちらか一方に対してのみ行えます。両方同時に実装することはできません。

抽象クラスから継承する際、親クラスの宣言で abstract としてマークされた 全てのメソッドは、子クラスで定義されなければなりません。加えて、 オブジェクトの継承 と シグネチャの互換性に関するルール に従わなければいけません。

PHP 8.4 から、抽象クラスは public または protected の抽象プロパティを宣言できるようになりました。 protected な抽象プロパティは、protected または public のスコープから読み書き可能なプロパティにより 要件が満たされます。

抽象プロパティは、通常のプロパティによって、または 必要な操作に対応した フック を定義したプロパティにより要件が満たされます。

例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

例3 抽象プロパティの例

    <?php

    abstract class A
    {
        // 継承するクラスは、public に読み取り可能なプロパティを持たなければなりません
        abstract public string $readable {
            get;
        }

        // 継承するクラスは、protected または public に書き込み可能なプロパティを持たなければなりません
        abstract protected string $writeable {
            set;
        }

        // 継承するクラスは、protected または public で読み書き可能なプロパティを持たなければなりません
        abstract protected string $both {
            get;
            set;
        }
    }

    class C extends A
    {
        // 要件を満たし、さらに書き込みも可能にしているため有効です
        public string $readable;

        // public に読み取り可能でないため、要件を満たしません
        protected string $readable;

        // 要件を正確に満たしているため有効です
        // protected のスコープからのみ書き込みが可能です
        protected string $writeable {
            set => $value;
        }

        // protected から public にアクセス権を拡張しており、問題ありません
        public string $both;
    }

    ?>

抽象プロパティにはフックを実装できます。 前の例のように、`get` または `set` のどちらかを、定義せず宣言のみ行います。

例4 フック付きの抽象プロパティの例

    <?php

    abstract class A
    {
        // set のデフォルト実装（オーバーライド可能）を提供し、
        // 子クラスが get を実装するよう要求しています
        abstract public string $foo {
            get;

            set {
                $this->foo = $value;
            }
        }
    }

    ?>

## オブジェクト インターフェイス

オブジェクト インターフェースでは、クラスが実装すべきメソッドやプロパティの 宣言だけを行うコードを作成できます。ここでは具体的な実装は必要ありません。 インターフェイスはクラス、トレイト、列挙型と名前空間を共有するので、 それらと同じ名前を使ってはいけません。

インターフェイスは通常のクラスと同様に定義することができますが、 キーワード `class` のかわりに `interface` を用います。またメソッドの実装は全く定義しません。

インターフェイス内で宣言される全てのメソッドは public である必要があります。 これは、インターフェイスの特性によります。

インターフェイスには、ふたつの互いを補完する役割があります。

- 同じインターフェイスを実装していることで、 開発者が交換可能な異なるクラスを作成できるようにします。 同じインターフェイスを持つクラスによくある例として、 複数のデータベースにアクセスするサービスや 決済のゲートウェイ、 異なるキャッシュ戦略が挙げられます。 実装が異なっていても、 それを使うコードに変更を加えることなく、それらを交換することができます。
- メソッドや関数が、インターフェイスを満たすパラメータを受け付け、 操作できるようにします。 オブジェクトが何をするのかや、 どう実装されているのかを気にする必要はありません。 振る舞いの重要性を説明するために、 `Iterable` や `Cacheable`、 `Renderable` のような名前が付けられることがよくあります。

インターフェイスは、 マジックメソッド を宣言しても問題ありません。

> 注意:

> コンストラクタ をインターフェイスで宣言できますが、全くおすすめできません。 そうしてしまうと、 インターフェイスを実装するクラスの柔軟性が大きく損なわれる上、 コンストラクタには継承ルールが適用されないため、 一貫しない、予期せぬ結果を生む可能性があるからです。

### `implements`

インターフェイスを実装するには、`implements` 演算子を使用し、 このインターフェイスに含まれる全てのメソッドを実装する必要があります。 実装されていない場合、致命的エラーとなります。 各インターフェイスをカンマで区切って指定することで、 クラスは複数のインターフェイスを実装することができます。

警告

インターフェイスを実装するクラスでは、 インターフェイス内の名前とは異なる名前を メソッドのパラメータに使うことができます。 しかし、PHP 8.0 以降では 名前付き引数 がサポートされています。 これは、メソッドをコールする側がインターフェイス内の名前に依存する可能性があるということです。 そうした理由から、開発者は実装されるインターフェイスと同じパラメータ名を使うことを強く推奨します。

> 注意:

> クラスと同様、インターフェイスも extends 演算子で継承することができます。

> 注意:

> インターフェイスを実装したクラスでは、 シグネチャの互換性に関するルール を守った形で、インターフェイス内の全てのメソッドを宣言しなければいけません。 クラスは、同じ名前のメソッドを定義した複数のインターフェイスを実装することが出来ます。 この場合、実装されるメソッドは全て、 シグネチャの互換性に関するルール に従わなければいけません。 そうすることで、共変性と反変性 のルールも適用できます。

### 定数

インターフェイスに定数を持たせることもできます。 インターフェイス定数は クラス定数 とまったく同じように動作します。 PHP 8.1.0 より前のバージョンでは、 そのインターフェイスを継承したクラスやインターフェイスから定数をオーバーライドすることができませんでした。

### プロパティ

PHP 8.4.0 から、インターフェイスはプロパティを宣言できるようになりました。 宣言する場合、そのプロパティの読み取り可否、書き込み可否、あるいは双方を 指定する必要があります。 インターフェイスによる宣言は、public な読み書きに対してのみ適用できます。

クラス側でインターフェイスのプロパティ要件を満たすには、 public な通常のプロパティを定義する、 対応するフックを実装する public な 仮想プロパティ を定義するなど、複数の方法があります。 読み取り用プロパティは `readonly` プロパティによって満たすこともできます。 ただし、インターフェイスで「書き込み可能」と宣言されているプロパティを `readonly` にすることはできません。

例1 インターフェイスのでのプロパティ宣言の例

    <?php
    interface I
    {
        // 実装クラスは、public に読み取り可能なプロパティを持つ必要があります。
        // public に書き込み可能かどうかは制限されません。
        public string $readable { get; }

        // 実装クラスは、public に書き込み可能なプロパティを持つ必要があります。
        // public に読み取り可能かどうかは制限されません。
        public string $writeable { set; }

        // 実装クラスは、public に読み書き可能なプロパティを持つ必要があります。
        public string $both { get; set; }
    }

    // このクラスは、3つのプロパティをすべてフックのない通常のプロパティとして実装しています。
    // これは問題ありません。
    class C1 implements I
    {
        public string $readable;

        public string $writeable;

        public string $both;
    }

    // このクラスは、3つのプロパティすべてを、要求されたフックのみを使って実装しています。
    // これも問題ありません。
    class C2 implements I
    {
        private string $written = '';
        private string $all = '';

        // get フックのみ使い仮想プロパティを作成しています。
        // 「public に読み取り可能」という要件を満たします。
        // 書き込みはできませんが、インターフェイスからは要求されていません。
        public string $readable { get => strtoupper($this->writeable); }

        // インターフェイスはこのプロパティが「書き込み可能」であることのみ要求しています。
        // ここに get の動作も含めることは全く問題ありません。
        // この例では仮想プロパティを作成しています。
        public string $writeable {
            get => $this->written;
            set {
                $this->written = $value;
            }
        }

        // このプロパティは「public に読み書き可能」でなければならないため、
        // get と set の両方を実装する必要があります。
        // デフォルトの動作のままでも問題ありません。
        public string $both {
            get => $this->all;
            set {
                $this->all = strtoupper($value);
            }
        }
    }
    ?>

### 例

例2 インターフェイスの例

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

例3 インターフェイスの継承

    <?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)
        {
        }
    }
    ?>

例4 共変性を保った形で、複数のインターフェイスを実装する

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

例5 複数のインターフェイスの継承

    <?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()
        {
        }
    }
    ?>

例6 インターフェイスでの定数

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

例7 抽象クラスとインターフェイス

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

例8 継承と実装を同時に行う

    <?php

    class One
    {
        /* ... */
    }

    interface Usable
    {
        /* ... */
    }

    interface Updatable
    {
        /* ... */
    }

    // ここでは、キーワードの順番が重要です。
    // 'extends' を始めに置かなければいけません。
    class Two extends One implements Usable, Updatable
    {
        /* ... */
    }
    ?>

インターフェイスと型宣言を組み合わせると、 特定のオブジェクトに特定のメソッドをうまく持たせることができます。 instanceof 演算子および 型宣言 を参照ください。

## トレイト

PHP は、コードを再利用するための「トレイト」という仕組みを実装しています。

トレイトは、PHP のような単一継承言語でコードを再利用するための仕組みのひとつです。 トレイトは、単一継承の制約を減らすために作られたもので、 いくつかのメソッド群を異なるクラス階層にある独立したクラスで再利用できるようにします。 トレイトとクラスを組み合わせた構文は複雑さを軽減させてくれ、 多重継承や Mixin に関連するありがちな問題を回避することもできます。

トレイトはクラスと似ていますが、トレイトは単にいくつかの機能をまとめるためだけのものです。 トレイト自身のインスタンスを作成することはできません。 昔ながらの継承に機能を加えて、振る舞いを水平方向で構成できるようになります。 つまり、継承しなくてもクラスのメンバーに追加できるようになります。

例1 トレイトの例

    <?php

    trait TraitA {
        public function sayHello() {
            echo 'Hello';
        }
    }

    trait TraitB {
        public function sayWorld() {
            echo 'World';
        }
    }

    class MyHelloWorld
    {
        use TraitA, TraitB; // A class can use multiple traits

        public function sayHelloWorld() {
            $this->sayHello();
            echo ' ';
            $this->sayWorld();
            echo "!\n";
        }
    }

    $myHelloWorld = new MyHelloWorld();
    $myHelloWorld->sayHelloWorld();

    ?>

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

    Hello World!

### 優先順位

基底クラスから継承したメンバーよりも、トレイトで追加したメンバーのほうが優先されます。 優先順位は現在のクラスのメンバーが最高で、その次がトレイトのメソッド、 そしてその次にくるのが継承したメソッドとなります。

例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!

### 衝突の解決

同じ名前のメンバーを含む複数のトレイトを追加するときには、 衝突を明示的に解決しておかないと 致命的なエラーが発生します。

同一クラス内での複数のトレイト間の名前の衝突を解決するには、 `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();
    $p = new C2();
    $p->inc();

    ?>

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

    1
    1

例10 staticメソッド

    <?php

    trait StaticExample
    {
        public static function doSomething()
        {
            return 'Doing something';
        }
    }

    class Example
    {
        use StaticExample;
    }

    echo Example::doSomething();

    ?>

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

    Doing something

例11 staticプロパティ

警告

PHP 8.3.0 より前のバージョンでは、トレイト中で定義された static プロパティは、 そのトレイトを use している同じ継承階層にある全てのクラスで共有されていました。 PHP 8.3.0 以降では、子クラスが static プロパティを持つトレイトを use している場合、 親クラスで定義された static プロパティとは別物とみなされるようになりました。

    <?php

    trait T
    {
        public static $counter = 1;
    }

    class A
    {
        use T;

        public static function incrementCounter()
        {
            static::$counter++;
        }
    }

    class B extends A
    {
        use T;
    }

    A::incrementCounter();

    echo A::$counter, "\n";
    echo B::$counter, "\n";

    ?>

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

    2
    1

### プロパティ

トレイトにはプロパティも定義できます。

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

### Final メソッド

PHP 8.3.0 以降では、`as` 演算子を使って final をトレイトからインポートしたメソッドに適用できるようになりました。 こうすることで、子クラスでそのメソッドをオーバーライドすることを防止できます。 しかし、トレイトを使うクラスは、未だそのメソッドをオーバーライドできます。

例16 トレイトからインポートするメソッドを `final` として定義する

    <?php

    trait CommonTrait
    {
        public function method()
        {
            echo 'Hello';
        }
    }

    class FinalExampleA
    {
        use CommonTrait {
            CommonTrait::method as final; // The 'final' prevents child classes from overriding the method
        }
    }

    class FinalExampleB extends FinalExampleA
    {
        public function method() {}
    }

    ?>

上の例の出力は、 たとえば以下のようになります。

    Fatal error: Cannot override final method FinalExampleA::method() in ...

## 無名クラス

無名クラスは、その場限りの使い捨てのオブジェクトが必要になった場合に便利です。

    <?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 8.3.0 以降では、 無名クラスにも `readonly` を適用できます。

例1 読み取り専用の無名クラスを定義する

    <?php
    // Using an anonymous class
    var_dump(new readonly class('[DEBUG]') {
        public function __construct(private string $prefix)
        {
        }

        public function log($msg)
        {
            echo $this->prefix . ' ' . $msg;
        }
    });

## オーバーロード

PHP におけるオーバーロード機能は、 プロパティやメソッドを動的に 作成する ための手法です。 これらの動的エンティティは、マジックメソッドを用いて処理されます。 マジックメソッドは、クラス内でさまざまなアクションに対して用意することができます。

オーバーロードメソッドが起動するのは、 宣言されていないプロパティやメソッドを操作しようとしたときです。 また、現在のスコープからは アクセス不能な プロパティやメソッドを操作しようとしたときにも起動します。 このセクションでは、これらの (宣言されていない、 あるいは現在のスコープからはアクセス不能な) プロパティやメソッドのことを アクセス不能プロパティ および アクセス不能メソッド と表記することにします。

オーバーロードメソッドは、すべて `public` で定義しなければなりません。

> 注意:

> これらのマジックメソッドの引数は、 リファレンス渡し とすることはできません。

> 注意:

> PHP における オーバーロード の解釈は、他の多くのオブジェクト指向言語とは異なります。 一般的に「オーバーロード」とは、 「名前は同じだけれども引数の数や型が異なるメソッドを複数用意できる」 という機能のことを指します。

### プロパティのオーバーロード

public function __set(string `$name`, mixed `$value`): void
public function __get(string `$name`): mixed
public function __isset(string `$name`): bool
public function __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;
        }
    }

    $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 function __call(string `$name`, array `$arguments`): mixed
public static function __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(), __serialize(), __unserialize(), __sleep(), __wakeup(), __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() については、戻り値の型を宣言してはいけません。 宣言してしまうと、致命的なエラーが発生します。

### __serialize() と __unserialize()

public function __serialize(): array
public function __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 以降で利用できます。

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

### __sleep() と __wakeup()

警告

このシリアル化の仕組みは、PHP 8.5.0 以降 soft-deprecated 扱いになりました。 後方互換性のために維持されていますが、新規コードおよび既存コードは、代わりに __serialize() と __unserialize() マジックメソッドを使うように移行すべきです。

public function __sleep(): array
public function __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() の使用目的は、 シリアル化の際に失われたデータベース接続を再度確立したり、 その他の再初期化を行うことです。

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

### __toString()

public function __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()

function __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 function __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()

function __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.4.0 以降)

    <?php
    class BaseClass {
       final protected string $test;
    }

    class ChildClass extends BaseClass {
        public string $test;
    }
    // Results in Fatal error: Cannot override final property BaseClass::$test
    ?>

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

> 注意: PHP 8.0.0 以降は、private メソッドを final として宣言できるのはコンストラクタだけになりました。

> 注意: `private(set)` として宣言されたプロパティは暗黙的に`final`になります。

## オブジェクトのクローン作成

オブジェクトのコピーを作成する際、そのプロパティも全て二重化することが、 常に望ましい動作であるわけではありません。 コピーコンストラクタが必要となる例として、 GTKウインドウを表すオブジェクトを有しており、 そのオブジェクトがGTKウインドウのリソースを保持している際、 コピーを作成する時に、同じプロパティを有するウインドウを作成し、 その新しいオブジェクトがその新しいウインドウのリソースを保持する ようにしたい場合が考えられます。 他の例としては、 オブジェクトがそのオブジェクトが使用する他のオブジェクトへのリファレンスを 保持しており、親オブジェクトをコピーする際に、そのコピーが独立したオブジェクトの コピーを有するように、そのオブジェクトのインスタンスを新たに作成したい場合が 考えられます。

オブジェクトのコピーは、clone キーワード (これは、そのオブジェクトの __clone() メソッドがある場合にこれをコールします)により作成されます。

    $copy_of_object = clone $object;

オブジェクトのクローンが作成される際、PHP は、そのオブジェクトのプロパティを 全てシャローコピーします。他の変数へのリファレンスを保持する全てのプロパティは、 リファレンスのままとなります。

function __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();
    try {
        $c->test();
    } catch (Error $e) {
        echo $e->getMessage();
    }

    ?>

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

    Success!
    Success!
    Success!
    Call to private method C::foo() from scope A

> 注意:

> 遅延静的束縛の解決は、:: を使ったコールが代替なしに完全に解決された時点で終了します。 一方、`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

### プロパティの共変性と反変性(変性)

デフォルトでは、プロパティは共変でも反変でもなく不変です。 つまり、子クラスでは型は変更できません。 「get」操作は共変でなければならず、 「set」操作は反変でなければならないことが理由です。 双方を同時に満たすには、プロパティは不変である必要があります。

PHP 8.4.0 から、インターフェイスや抽象クラスでの抽象プロパティや、 仮想プロパティ が追加されたことにより、 プロパティが「get」または「set」だけを持つことを宣言できるようになりました。 つまり、「get」操作だけが必要な抽象プロパティや仮想プロパティは共変性を持ちます。 同様に、「set」操作だけが必要な抽象プロパティや仮想プロパティは反変性を持ちます。

ただし、いったんプロパティが「get」と「set」操作の両方を持つようになると、 それ以上の拡張において共変あるいは反変にはなりません。 その時点で不変となります。

例1 プロパティの型の変性

    <?php
    class Animal {}
    class Dog extends Animal {}
    class Poodle extends Dog {}

    interface PetOwner
    {
        // 必要なのは「get」操作のみなので、共変です
        public Animal $pet { get; }
    }

    class DogOwner implements PetOwner
    {
        // 「get」が Animal を返す限り、より狭い型に変更できます。
        // しかし、これは通常のプロパティなので、
        // 子クラスでは型を変更できません。
        public Dog $pet;
    }

    class PoodleOwner extends DogOwner
    {
        // これは許可されません。
        // DogOwner::$pet は「get」「set」両方の操作を持つためです。
        public Poodle $pet;
    }
    ?>

## レイジーオブジェクト

レイジーオブジェクトは、状態が参照または変更されるまで 初期化が遅延されるオブジェクトです。ユースケースの例として、 必要な時だけ初期化される遅延DIコンポーネント、 必要な時だけデータを読み込む遅延ORM、 必要な時だけ解析を行う遅延JSONパーサーなどがあります。

レイジーオブジェクトには、ゴーストオブジェクトとバーチャルプロキシの 2つの戦略があります。以降 "レイジーゴースト"、 "レイジープロキシ" と呼びます。 どちらの戦略の場合も、レイジーオブジェクトには 最初に状態が参照または変更されたときに自動的に呼び出されるイニシャライザまたはファクトリが 接続されています。抽象的な観点では、レイジーゴーストオブジェクトは 非レイジーなものと区別がつかず、レイジーであること意識せず使用できます。 レイジープロキシも同様に透過的ですが、実体を 参照する際は注意が必要です。プロキシと実インスタンスは異なる実体を 持つからです。

> 注意: バージョン情報
> レイジーオブジェクトは、PHP 8.4 で実装されました。

### レイジーオブジェクトの作成

任意のユーザー定義クラスやstdClassクラス （他の内部クラスはサポートされていません）のレイジーインスタンスを作成したり、 これらのクラスのインスタンスをレイジーにリセットすることが可能です。 レイジーオブジェクトを作成するエントリーポイントは、 ReflectionClass::newLazyGhost()および ReflectionClass::newLazyProxy()メソッドです。

どちらのメソッドも、オブジェクトの初期化が必要な際に呼び出される関数を 受け取ります。その関数が要求する動作は、使用する戦略に応じて 異なります。各メソッドのリファレンスを参照してください。

例1 レイジーゴーストの作成

    <?php
    class Example
    {
        public function __construct(public int $prop)
        {
            echo __METHOD__, "\n";
        }
    }

    $reflector = new ReflectionClass(Example::class);
    $lazyObject = $reflector->newLazyGhost(function (Example $object) {
        // ここでオブジェクトを初期化
        $object->__construct(1);
    });

    var_dump($lazyObject);
    var_dump(get_class($lazyObject));

    // ここで初期化がトリガーされる
    var_dump($lazyObject->prop);
    ?>

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

    lazy ghost object(Example)#3 (0) {
    ["prop"]=>
    uninitialized(int)
    }
    string(7) "Example"
    Example::__construct
    int(1)

例2 レイジープロキシの作成

    <?php
    class Example
    {
        public function __construct(public int $prop)
        {
            echo __METHOD__, "\n";
        }
    }

    $reflector = new ReflectionClass(Example::class);
    $lazyObject = $reflector->newLazyProxy(function (Example $object) {
        // 実インスタンスを初期化して返す
        return new Example(1);
    });

    var_dump($lazyObject);
    var_dump(get_class($lazyObject));

    // ここで初期化がトリガーされる
    var_dump($lazyObject->prop);
    ?>

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

    lazy proxy object(Example)#3 (0) {
      ["prop"]=>
      uninitialized(int)
    }
    string(7) "Example"
    Example::__construct
    int(1)

レイジーオブジェクトのプロパティへのアクセスは、初期化をトリガーします (ReflectionProperty 経由も含む)。 しかし、特定のプロパティに対してはトリガーしないよう、 事前に初期化しておく必要があるかもしれません。

例3 プロパティを事前に初期化する

    <?php
    class BlogPost
    {
        public function __construct(
            public int $id,
            public string $title,
            public string $content,
        ) { }
    }

    $reflector = new ReflectionClass(BlogPost::class);

    $post = $reflector->newLazyGhost(function ($post) {
        $data = fetch_from_store($post->id);
        $post->__construct($data['id'], $data['title'], $data['content']);
    });

    // この行がないと、次のReflectionProperty::setValue()の呼び出しは
    // 初期化をトリガーします。
    $reflector->getProperty('id')->skipLazyInitialization($post);
    $reflector->getProperty('id')->setValue($post, 123);

    // または、直接以下を使用できます:
    $reflector->getProperty('id')->setRawValueWithoutLazyInitialization($post, 123);

    // 事前に設定したidプロパティは初期化をトリガーせずにアクセスできます
    var_dump($post->id);
    ?>

ReflectionProperty::skipLazyInitialization() および ReflectionProperty::setRawValueWithoutLazyInitialization() メソッドで、プロパティにアクセスする際の遅延初期化をバイパスできます。

### レイジーオブジェクトの戦略について

レイジーゴーストは、その場で初期化され、 初期化後はレイジーでないオブジェクトと区別がつきません。 この戦略は、オブジェクトのインスタンス化と初期化の両方を 制御できる場合に適しています。どちらかを制御出来ない場合は 適していません。

レイジープロキシは、初期化後、実インスタンスへの プロキシとして機能します。初期化されたレイジープロキシ上のあらゆる操作は、 実インスタンスに転送されます。この戦略は、インスタンスの作成を 外部に委ねているなど、レイジーゴーストが適さない場合に 適しています。レイジープロキシはほぼ透過的ですが、インスタンスの実体を 使用する場合は注意が必要です。プロキシと実インスタンスは異なる 実体を持つからです。

### レイジーオブジェクトのライフサイクル

オブジェクトは、インスタンス化時に ReflectionClass::newLazyGhost()または ReflectionClass::newLazyProxy()を使用して、 あるいはインスタンス化後に ReflectionClass::resetAsLazyGhost()または ReflectionClass::resetAsLazyProxy()を使用して、 レイジーにできます。その後、以下のいずれかの操作により初期化されます:

- 自動初期化をトリガーする方法でオブジェクトと対話する。 初期化トリガーを 参照してください。
- ReflectionProperty::skipLazyInitialization()または ReflectionProperty::setRawValueWithoutLazyInitialization()を使用して、 すべてのプロパティを非レイジーとしてマークする。
- ReflectionClass::initializeLazyObject()または ReflectionClass::markLazyObjectAsInitialized()を 明示的に呼び出す。

すべてのプロパティが非レイジーとしてマークされると、レイジーオブジェクトは 初期化済とみなされます。従って上記のメソッドは、非レイジーなプロパティがない場合、 オブジェクトをレイジーとみなしません。

### 初期化トリガー

レイジーオブジェクトは、利用者に対して透過的に設計されているため、 オブジェクトの状態を参照または変更する通常の操作は、 その実行の前に自動的に初期化をトリガーします。これには以下の操作が含まれますが、 これらに限定されません:

- プロパティの読み取りまたは書き込み。
- プロパティが設定されているかテスト、またはプロパティの削除。
- ReflectionProperty::getValue()、 ReflectionProperty::getRawValue()、 ReflectionProperty::setValue()、 ReflectionProperty::setRawValue() によるプロパティの参照または変更。
- ReflectionObject::getProperties()、 ReflectionObject::getProperty()、 get_object_vars() によるプロパティの取得。
- Iteratorや IteratorAggregateを 実装していないオブジェクトを foreachでイテレーション。
- serialize()、 json_encode()などでシリアライズ。
- クローンの作成。

オブジェクトの状態にアクセスしないメソッド呼び出しは初期化を トリガーしません。同様に、マジックメソッドやフック関数を呼び出す オブジェクトとの対話も、これらのメソッドや関数がオブジェクトの状態に アクセスしない限りトリガーしません。

#### 初期化をトリガーしない操作

以下の特定のメソッドや低レベルの操作は、初期化をトリガーせずにレイジー オブジェクトへのアクセスや変更を可能にします:

- ReflectionProperty::skipLazyInitialization() や ReflectionProperty::setRawValueWithoutLazyInitialization() でプロパティを非レイジーとしてマーク。
- get_mangled_object_vars() や、 配列への変換による プロパティ内部表現の取得。
- `ReflectionClass::SKIP_INITIALIZATION_ON_SERIALIZE` が設定された状態での serialize() 。 ただし __serialize() または __sleep() が初期化をトリガーしない場合。
- ReflectionObject::__toString() の呼び出し。
- var_dump() または debug_zval_dump() 。ただし、 __debugInfo() が初期化をトリガー しない場合に限る。

### 初期化シーケンス

このセクションでは、初期化がトリガーされたときに実行される操作の順序を 使用する戦略に応じて説明します。

#### ゴーストオブジェクト

- オブジェクトは非レイジーとしてマークされます。
- ReflectionProperty::skipLazyInitialization()または ReflectionProperty::setRawValueWithoutLazyInitialization() で初期化されていないプロパティは、デフォルト値があれば それに設定されます。結果的に、事前に初期化済のプロパティを除き、 ReflectionClass::newInstanceWithoutConstructor() でと似たオブジェクトになります。
- そのオブジェクトをパラメータとして、イニシャライザ関数が呼び出されます。 この関数は、オブジェクトの状態を初期化することが 期待されますが、必須ではありません。`null` を返すか、値を返さない必要があります。 オブジェクトはもはやレイジーではないので、 関数はプロパティに直接アクセスできます。

初期化後、オブジェクトはレイジーでない場合と 区別がつきません。

#### プロキシオブジェクト

- オブジェクトは非レイジーとしてマークされます。
- ゴーストオブジェクトとは異なり、この段階でオブジェクトのプロパティは 変更されません。
- オブジェクトがファクトリ関数に入力されます。 この関数は、互換性のあるクラスの非レイジーなインスタンスを返す必要があります （ReflectionClass::newLazyProxy()を参照）。
- 返されたインスタンスは 実インスタンス として参照され、 プロキシに接続されます。
- プロキシのプロパティ値は、 unset() と同等の方法で破棄されます。

初期化後、プロキシの任意のプロパティへのアクセスは、 実インスタンスへのアクセスと同じ結果をもたらします。 宣言済プロパティ、動的プロパティ、存在しないプロパティ、 ReflectionProperty::skipLazyInitialization() や ReflectionProperty::setRawValueWithoutLazyInitialization() で マークされたプロパティを含む、すべてのプロパティへのアクセスは 実インスタンスに転送されます。

プロキシオブジェクトが、 実インスタンスに置き換えられることはありません。

ファクトリは最初のパラメータとしてプロキシを受け取りますが、 それを変更することは期待されていません（変更は許可されますが、 最終的な初期化ステップ中に失われます）。しかし、プロキシは 事前に初期化されたプロパティの値、クラス、オブジェクト自体、 その同一性に基づく決定に使用できます。例えば、イニシャライザは 実インスタンスを作成する際に初期化されたプロパティの値を利用するかもしれません。

#### 共通の動作

イニシャライザまたはファクトリ関数のスコープと$thisの コンテキストは変更されず、通常の可視性制約が適用されます。

初期化が成功した後、イニシャライザまたはファクトリ関数は オブジェクトから参照されなくなり、他に参照がなければ 解放される場合があります。

イニシャライザが例外をスローした場合、オブジェクトの状態は 初期化前の状態に戻され、オブジェクトは再びレイジーとマークされます。つまり、 オブジェクトへの副作用はすべて破棄されます。これは、失敗した場合に 壊れたインスタンスが生成されてしまうのを防ぎます。ただし、他のオブジェクトへの 影響など、外部への副作用は元に戻されません。

### クローン

レイジーオブジェクトをクローンすると、 クローンが作成される前に初期化がトリガーされ、 結果として初期化されたオブジェクトが得られます。

プロキシオブジェクトの場合、プロキシとその実インスタンスの両方がクローンされ、 プロキシのクローンが返されます。 `__clone`メソッドは プロキシではなく実インスタンス上で呼び出されます。 クローンされたプロキシと実インスタンスは 初期化時にリンクされるため、クローン後のプロキシへのアクセスは クローン後の実インスタンスに転送されます。

この動作により、クローンと元のオブジェクトは独立した状態を持つことが 保証されます。クローン後に元のオブジェクトまたはそのイニシャライザの状態に 変更を加えても、クローンには影響しません。実インスタンスのみではなく 両方をクローンすることで、クローン操作は常に同じクラスのオブジェクトを 返すことを保証します。

### デストラクタ

レイジーゴーストの場合、オブジェクトが初期化されている場合のみ、 プロキシの場合、実インスタンスが存在する場合のみ、 デストラクタが呼び出されます。

ReflectionClass::resetAsLazyGhost()および ReflectionClass::resetAsLazyProxy()メソッドは、 リセットされるオブジェクトのデストラクタを呼び出す場合があります。

## 変更履歴

PHP の OOP モデルの変更履歴をここに記録します。 個々の機能の説明や注意点については、クラスとオブジェクトに関するドキュメントを参照ください。

バージョン | 説明
--- | ---
8.4.0 | プロパティフック がサポートされました。
8.4.0 | レイジーオブジェクトがサポートされました。
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;
    print $a::class . "\n";
    $c = new \my\name\MyClass; // "グローバル空間" を参照ください
    print $c::class . "\n";

    $a = strlen('hi'); // "名前空間の使用法: グローバル関数/定数への
                       // 移行" を参照ください
    print $a . "\n";

    $d = namespace\MYCONST; // "namespace 演算子および __NAMESPACE__ 定数"
                            // を参照ください
    print $d . "\n";
    $d = __NAMESPACE__ . '\MYCONST';
    echo constant($d); // "名前空間および動的言語機能" を参照ください

> 注意: 名前空間の名前は、大文字小文字を区別しません。

> 注意:

> 名前空間の名前として `PHP` や これらで始まる名前 (`PHP\Classes` など) は 言語の内部で使うために予約されており、ユーザーのコードで使うべきではありません。

## 名前空間の定義

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

PHP のコードならなんでも名前空間に含めることができますが、 実際に名前空間の影響を受けるのはクラス (抽象クラスやトレイト、列挙型(Enum) を含む) とインターフェイス、関数、そして定数だけです。

名前空間を宣言するには、キーワード `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 {
        public static function start() {
            print __METHOD__ . "\n";
        }
    }

    function connect() {
        print __FUNCTION__ . "\n";
    }
    }

    namespace { // グローバルコード
    print strlen("hi") . "\n";
    MyProject\connect();
    MyProject\Connection::start();
    }

namespace の波括弧の外側に書くことができる PHP コードは、最初の declare 文だけです。

例4 複数の名前空間および名前空間に属さないコードの宣言

    <?php
    declare(strict_types=1);
    namespace MyProject {

    const CONNECT_OK = 1;
    class Connection {
        public static function start() {
            print __METHOD__ . "\n";
        }
    }

    function connect() {
        print __FUNCTION__ . "\n";
    }
    }

    namespace { // グローバルコード
    print strlen("hi") . "\n";
    MyProject\connect();
    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 {}

    print \strlen('hi') . "\n"; // グローバル関数 strlen をコールします
    print \INI_ALL . "\n"; // グローバル定数 INI_ALL にアクセスします
    $c = new \Exception('error'); // グローバルクラス Exception のインスタンスを作成します
    print $c::class . "\n";

## 名前空間と動的言語機能

(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 クラスのオブジェクトです
    var_dump($a::class);
    $b = new \Exception('hi'); // $b は Exception クラスのオブジェクトです
    var_dump($b::class);

    $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;
    print $a::class;

これは、機能的に次と同等です。

例2 名前空間の外部にあるグローバルクラスへのアクセス

    <?php
    $a = new stdClass;
    print $a::class;

### 名前空間内での内部クラスあるいはグローバルクラスの使用法は?

例3 名前空間内からの内部クラスへのアクセス

    <?php
    namespace foo;
    $a = new \stdClass;
    print $a::class . "\n";

    function test(?\ArrayObject $parameter_type_example = null) {}

    $a = \FilesystemIterator::CURRENT_AS_FILEINFO;
    print $a . "\n";

    // 内部クラス/グローバルクラスの継承
    class MyException extends \Exception {}
    print MyException::class . "\n";

### 同じ名前空間にあるクラス、関数あるいは定数を使用する方法は?

例4 名前空間内のクラス、関数あるいは定数へのアクセス

    <?php
    namespace foo;

    class MyClass {}

    // 現在の名前空間のクラスをパラメータの型として使う
    function test(?MyClass $parameter_type_example = null) {}
    // 現在の名前空間のクラスをパラメータの型として使うもうひとつの方法
    function test2(?\foo\MyClass $parameter_type_example = null) {}

    // 現在の名前空間のクラスの継承
    class Extended extends MyClass {}
    print Extended::class . "\n";

    // グローバル関数へのアクセス
    $a = \strlen("test");
    print $a . "\n";

    // グローバル定数へのアクセス
    $b = \INI_ALL;
    print $b . "\n";

### `\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() {
        print __FUNCTION__ . "\n";
    }
    function foo() {
        print __FUNCTION__ . "\n";
    }
    function sort(&$a)
    {
        \sort($a); // グローバル関数 "sort" をコールします
        $a = array_flip($a);
        return $a;
    }

    my(); // "foo\my" をコールします
    print strlen('hi') . "\n"; // "foo\strlen" が存在しないので、グローバル関数 "strlen" をコールします
    $arr = array(1,3,2);
    $b = sort($arr); // "foo\sort" 関数をコールします
    var_dump($b);
    foo(); // calls function "foo\foo" - import is not applied

    $a = FOO; // sets $a to value of constant "foo\FOO" - import is not applied
    print $a;
    $b = INI_ALL; // sets $b to value of global constant "INI_ALL"
    print $b;

### インポートした名前が同一ファイルで定義されているクラスと衝突してはいけない

次のようなスクリプトの組み合わせは、正当なものです。

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

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    function pick_a_card(Suit $suit)
    {
        var_dump($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

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    $a = Suit::Spades;
    $b = Suit::Spades;

    if ($a === $b) {
        print "Suits match using ===\n";
    }

    if ($a instanceof Suit) {
        print "Suits match using instanceof\n";
    }

    if ($a !== 'Spades') {
        print "Suit does not match the string\n";
    }

このことは、列挙型の値は決して `<` や `>` で比較できないことも意味しています。 なぜなら、それらの比較をオブジェクトで行っても無意味だからです。 列挙型の値を使ってこれらの比較を行っても、常に `false` を返します。

関連するデータのない、こうしたタイプの case を、 "Pure Case" と呼びます。 Pure Case のみを含む列挙型を、"Pure Enum" と呼びます。

全ての Pure Case は、その列挙型のインスタンスとして実装されています。 列挙型は内部的にクラスとして表現されます。

全ての case は読み取り専用のプロパティ `name` を持ちます。 これは大文字小文字が区別される、case そのものの名前です。

    <?php

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    print Suit::Spades->name;
    // "Spades" と表示

列挙型の名前を動的に取得している場合、 case の存在を確認したり、読み取る用途として defined() や constant() 関数が使えます。 しかしながら、これらの関数の利用はおすすめできません。 なぜなら、 Backed Enum で大半の用途を満たせるはずだからです。

## 値に依存した列挙型(Backed Enum)

デフォルトでは、列挙型はスカラー値の情報を持っていません。 単なるシングルトンオブジェクトです。 しかし、列挙型の 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 を参照していても構わないので、 別名を作成することはできます。 列挙型と定数 も参照ください。

スカラー値は、定数のスカラー式でなければいけません。 PHP 8.2.0 より前のバージョンでは、 スカラー値はリテラルか、リテラルを表す式でなければいけませんでした。 これは、定数や定数式はサポートされていなかったことを意味します。 つまり、`1 + 1` は許されますが、 `1 + SOME_CONST` は許されていませんでした。

Backed Enum の case は、追加の読み取り専用のプロパティ `value` を持っています。 これは、Backed Enum の定義で指定された値です。

    <?php

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    print Suit::Clubs->value;
    // "C" と表示

`value` プロパティを強制的に読み取り専用にするため、 そのリファレンスを変数には代入できません。 つまり、以下のようなコードはエラーになります:

    <?php

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    $suit = Suit::Clubs;
    $ref = &$suit->value;
    // Fatal Error: Cannot indirectly modify readonly 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

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    function get_stuff_from_database($id) {
        return [
            'suit' => 'S',
        ];
    }

    $record = get_stuff_from_database(42);
    print $record['suit'] . "\n";

    $suit = Suit::tryFrom('A') ?? Suit::Spades;
    // 不正なデータに対しては null を返すので、Suit::Spades が代わりに使われます。
    print $suit->value . "\n";

    $suit =  Suit::from('X');
    // 不正なデータを渡すと、次のようなエラーが発生 -> ValueError: "X" is not a valid backing scalar value for enum Suit
    print $suit->value . "\n";

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)
    {
       print $c->color() . "\n";
    }

    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): self
        {
            return match (true) {
                $cm < 50 => self::Small,
                $cm < 100 => self::Medium,
                default => self::Large,
            };
        }
    }

    var_dump(Size::fromLength(50));

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;
    }

    var_dump(Size::Huge);

## トレイト

列挙型ではトレイトを使えます。 列挙型におけるトレイトは、クラスにおけるそれと同じ振る舞いをします。 注意すべきことは、列挙型で `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',
            };
        }
    }

    $suit = Suit::Spades;
    var_dump($suit->color());
    var_dump($suit->shape());

## 定数式における列挙型の値

列挙型の 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
    }

    // これは、完全に正しいコードです。定数式ではないからです。
    $x = Direction::Up['short'];
    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

    enum Suit
    {
        case Hearts;
        case Diamonds;
        case Clubs;
        case Spades;
    }

    var_dump(Suit::cases());

    enum SuitBacked: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    var_dump(SuitBacked::cases());

列挙型において、手動で `cases()` メソッドを定義すると、致命的なエラーが発生します。

## 列挙型をシリアライズする

列挙型は、オブジェクトとは違う形でシリアライズされます。 特別に、列挙型には case 名を指定する新しいシリアライズコード "E" が付与されています。 アンシリアライズのルーチンはそれを使って、 既存のシングルトンの値を変数に設定できます。 これにより、以下のようなコードが動作することが保証されます:

    <?php

    enum Suit: string
    {
        case Hearts = 'H';
        case Diamonds = 'D';
        case Clubs = 'C';
        case Spades = 'S';
    }

    Suit::Hearts === unserialize(serialize(Suit::Hearts));

    print serialize(Suit::Hearts);
    // E:11:"Suit:Hearts";

アンシリアライズする際に、 マッチする列挙型と case がシリアライズした値に見つからなかった場合は、 警告が発生し、`false` が返されます。

unserialize() の `allowed_classes` オプションは、 列挙型(Enum) には影響しません。

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) {
                self::Pending => 'Pending',
                self::Active => 'Active',
                self::Suspended => 'Suspended',
                self::CanceledByUser => 'Canceled by user',
            };
        }
    }

    $status = UserStatus::Suspended;
    var_dump($status->label());

この例では、ユーザーのステータスは `UserStatus::Pending`、 `UserStatus::Active`、 `UserStatus::Suspended` または `UserStatus::CanceledByUser` のうちのひとつに限られています。 関数はパラメータの型を `UserStatus` に指定できますし、これら4つの値だけを受け入れます。

これら4つの値は、それぞれ `label()` メソッドを持ちます。 これは、人間が読みやすい文字列を返します。 この文字列は、"マシン上の" スカラー値とは別のものです。 このスカラー値は、データベースのフィールドや、 HTML の select ボックスで使うことができます。

    <?php

    enum UserStatus: string
    {
        case Pending = 'P';
        case Active = 'A';
        case Suspended = 'S';
        case CanceledByUser = 'C';

        public function label(): string
        {
            return match($this) {
                self::Pending => 'Pending',
                self::Active => 'Active',
                self::Suspended => 'Suspended',
                self::CanceledByUser => 'Canceled by user',
            };
        }
    }

    foreach (UserStatus::cases() as $case) {
        printf(
            "<option value=\"%s\">%s</option>\n",
            htmlentities($case->value),
            htmlentities($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
    - RequestParseBodyException
  - Exception
    - ...

# 例外(exceptions)

## 目次

- 例外を拡張する

> 注意: Exception クラスも参照ください

PHP は、他のプログラミング言語に似た例外モデルを持っています。 PHP 内で例外がスローされ (`throw` され)、それが 捕捉され (`catch` され) ます。発生した例外を 捕捉するには、コードを `try` ブロックで囲みます。 各 `try` ブロックには、対応する `catch` ブロックあるいは `finally` ブロックが存在する必要があります。

例外がスローされ、現在の関数スコープに `catch` ブロックがなかった場合、 その例外は、マッチする `catch` ブロックが見つかるまで関数のコールスタックを "遡って" いきます。 その途中で見つかった全ての `finally` ブロックが実行されます。 グローバルスコープに遡るまで全てのコールスタックを探しても、 マッチする `catch` ブロックが見つからない場合は、 グローバルな例外ハンドラが設定されていない限り fatal error となり、 プログラムが終了します。

スローされるオブジェクトは、 `instanceof` 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` ブロックから値が返されます。

`try` ブロック内でスローされた例外と、 `finally` ブロック内でスローされた例外には、 もう一つ注意すべき相互作用があります。 これら両方のブロックから例外がスローされると、 `finally` ブロックからスローされた例外は伝播しますが、 `try` ブロック内でスローされた例外は前の例外として使われます。

## グローバルな例外ハンドラ

例外がグローバルスコープにまで遡った場合、 設定されていれば、グローバルな例外ハンドラがそれをキャッチすることができます。 他の `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.";
    }

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

    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');
    }

    function do_something_risky() {
        return false; // Simulate failure
    }

    try {
        test();
    } catch (Exception $e) {
        print $e->getMessage();
    }

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

    It did not work

例9 try と finally の内部からスローされる例外

    <?php

    try {
        try {
            throw new Exception(message: 'Third', previous: new Exception('Fourth'));
        } finally {
            throw new Exception(message: 'First', previous: new Exception('Second'));
        }
    } catch (Exception $e) {
        var_dump(
            $e->getMessage(),
            $e->getPrevious()->getMessage(),
            $e->getPrevious()->getPrevious()->getMessage(),
            $e->getPrevious()->getPrevious()->getPrevious()->getMessage(),
        );
    }

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

    string(5) "First"
    string(6) "Second"
    string(5) "Third"
    string(6) "Fourth"

## 例外を拡張する

組み込みの 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

        // Overridable
        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;
            }
        }
    }

    echo "# Example 1\n";
    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# Example 2\n";
    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# Example 3\n";
    try {
        $o = new TestException(TestException::THROW_CUSTOM);
    } catch (Exception $e) {        // ここでキャッチされる
        echo "Default Exception caught\n", $e;
    }

    // 実行を継続する
    var_dump($o); // Null

    echo "\n\n# Example 4\n";
    try {
        $o = new TestException();
    } catch (Exception $e) {        //  スキップされる、例外は発生しない
        echo "Default Exception caught\n", $e;
    }

    // 実行を継続する
    var_dump($o); // TestException

# ファイバー

### ファイバーの概要

(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() から値が返されます(または、例外がスローされます)。

> 注意: PHP 8.4.0 より前のバージョンでは ファイバーをオブジェクトの デストラクタ 中で切り替えることはできませんでした。

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

PHP のアトリビュートは、クラス、メソッド、関数、パラメータ、プロパティ、定数に、 構造化され、かつマシンが読み取り可能なメタデータを提供します。 これらは リフレクション API を介して実行時に検査でき、 コードを変更することなく動的な振る舞いを可能にします。 アトリビュートは、宣言的な方法でコードにメタデータの注釈を付ける方法を提供します。

アトリビュートは、機能の実装と利用を分離できるようにします。 インターフェイスがメソッドを強制することで構造を定義するのに対し、 アトリビュートはメソッド、関数、プロパティ、定数を含む、 複数の要素にわたってメタデータを提供します。 インターフェイスがメソッドの実装を強制するのとは異なり、 アトリビュートはコードの構造を変更することなく注釈を付けます。

アトリビュートは、強制された構造の代わりにメタデータを提供することで、 オプションのインターフェイスメソッドを補完または置き換えることができます。 アプリケーションでの操作を表す `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);

## アトリビュートの文法

アトリビュートの文法は、いくつかの重要な要素で構成されています。 アトリビュートの宣言は `#[` で始まり、`]` で終わります。 その内部には、1つ以上のアトリビュートをカンマで区切って並べることができます。 アトリビュート名は、名前空間の基礎 で説明されているように、 非修飾名、修飾名、または完全修飾名にすることができます。 アトリビュートへの引数はオプションで、括弧 `()` で囲みます。 引数にはリテラル値または定数式のみを指定できます。 位置引数と名前付き引数の両方の構文がサポートされています。

アトリビュート名とその引数はクラスに解決され、 リフレクション 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
    #[Attribute]
    class MyAttribute
    {
        public $value;

        public function __construct($value)
        {
            $this->value = $value;
        }
    }

    #[MyAttribute(value: 1234)]
    class Thing
    {
    }

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

## アトリビュートクラスを宣言する

アトリビュートごとに個別のクラスを定義することをお勧めします。 最も単純なケースでは、`#[Attribute]` 宣言を持つ空のクラスで十分です。 このアトリビュートは、`use` 文を使用してグローバル名前空間からインポートできます。

例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`

デフォルトでは、アトリビュートは宣言ごとに1回しか使用できません。 アトリビュートを繰り返し可能にするには、 `#[Attribute]` 宣言のビットマスクで `Attribute::IS_REPEATABLE` フラグを指定します。

例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); */
    var_dump($a);
    var_dump($b);

しかし、配列の内部のリファレンスは危険もあるということに気をつけましょう。 通常の (リファレンスではない) 代入の右辺にリファレンスを使っても 左辺がリファレンスに変わることはありませんが、配列の内部のリファレンスは通常の代入においても維持されます。 これは、関数をコールする際に配列をリファレンスで渡すときも同じです。 たとえば、次のようになります。

    <?php

    /* スカラー変数への代入 */
    $a = 1;
    $b =& $a;
    $c = $b;
    $c = 7; // $c はリファレンスではないので $a や $b の値は変わりません
    print "a = {$a}; b = {$b}; c = {$c}\n\n";

    /* 配列変数への代入 */
    $arr = array(1);
    $a =& $arr[0]; // $a および $arr[0] は同じリファレンスセットになります
    $arr2 = $arr; // これは、リファレンス代入ではありません!
    $arr2[0]++;
    /* $a == 2, $arr == array(2) */
    /* $arr の内容は、たとえリファレンスでなくても変わります! */
    print "a = {$a}\n";
    var_dump($arr);
    var_dump($arr2);

言い換えると、配列内のリファレンスの挙動はその要素ごとに決まるということです。 個々の要素のリファレンスに関する動きは、 配列コンテナがリファレンスであるかどうかとは独立しています。

### リファレンス渡し

リファレンスの第 2 の使用法は、変数のリファレンス渡しです。この場合、 関数でローカル変数が作成され、コール側の変数が、それと同じ内容への リファレンスとなります。例を示します。

    <?php
    function foo(&$var)
    {
      $var++;
    }

    $a = 5;
    foo($a);
    print $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);
    print $a; // $a はここでは 6 です

> 注意: 関数コールの際には、リファレンス記号がないことに注意してください。 関数定義にのみリファレンス記号があります。リファレンスで正しく引数を 渡すには、関数定義のみで十分です。

次のものはリファレンスで渡すことが可能です。

- 変数、すなわち、`foo($a)`

- 関数から返されるリファレンスは、次のようになります。

      <?php

      function foo(&$var)
      {
          $var++;
          print $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 は、関数内の static な配列を指すリファレンスになりました。

    $collection[] = 'foo';

    print_r(collector());

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

    Array
    (
        [0] => foo
    )

> 注意: `$collection = collector();` のような形で、 `&` を使わずに代入が行われると、 変数 $collection は値のコピーを受け取ります。 関数から返されたリファレンスではありません。

返されたリファレンスを、リファレンスを要求する別の関数に渡すには、 この構文を使います。

    <?php

    function &collector()
    {
      static $collection = array();
      return $collection;
    }

    array_push(collector(), 'foo');

> 注意: `array_push(&collector(), 'foo');` は 動かないことに注意しましょう。致命的なエラーとなります。

## リファレンスの解除

リファレンスを解除することは、ちょうど変数名と変数の内容の結合を 解除することに相当します。これは、変数の内容が破棄されることを 意味しません。例えば、

    <?php

    $a = 1;
    $b =& $a;
    unset($a);
    var_dump($a);
    var_dump($b);

は、$b を削除せず、$a のみを 削除します。

ここでも、Unix の unlink コールと類似したものと 考えると便利です。

## リファレンスの適用範囲

PHP の多くの構文構造は、リファレンス機構を利用して実装されています。 このため、前記のリファレンス結合に関する事項はこれらの構造についても 適用されます。リファレンス渡しおよびリファレンスの戻り値のような いくつかの構造について前節で記述されています。リファレンスを使用する 他の構造には次のものがあります。

### global リファレンス

変数を global $var として宣言した場合、実際には グローバル変数へのリファレンスを作成したことになります。この意味は、 次の例と同じです。

    <?php
    $var =& $GLOBALS["var"];

これは、例えば、$var を削除してもグローバル変数は 削除されないことを意味します。

# 定義済みの変数

PHP には定義済みの定数が用意されています。 外部から来る変数 や組み込みの環境変数、そしてスクリプトに渡した引数の数や値のような、 実行環境に関するその他の情報の定数があります。

# スーパーグローバル

スーパーグローバル — すべてのスコープで使用できる組み込みの変数

### 説明

PHP の定義済み変数の中には "スーパーグローバル" というものがあります。 これは、スクリプト全体を通してすべてのスコープで使用可能な変数のことです。 関数やメソッドの内部からアクセスする際にも global $variable; などとする必要はありません。

スーパーグローバルには次のようなものがあります。

- $GLOBALS
- $_SERVER
- $_GET
- $_POST
- $_FILES
- $_COOKIE
- $_SESSION
- $_REQUEST
- $_ENV

### 注意

> 注意: 使用できる変数

> デフォルトでは、すべてのスーパーグローバルが使用可能です。 ただし、それに影響を与える設定項目もあります。詳細は variables_order のドキュメントを参照ください。

> 注意: 可変変数

> スーパーグローバルは、関数やクラスメソッドの中の 可変変数 として使用することはできません。

### 参考

- 変数のスコープ
- variables_order ディレクティブ
- filter 拡張モジュール

# $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;
>     }

>     ?>

# $_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'
  PHP がリクエストの処理を開始した時のタイムスタンプ。
'REQUEST_TIME_FLOAT'
  PHP がリクエストの処理を開始した時のタイムスタンプ (マイクロ秒までの精度)。
'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 拡張モジュール

# $_GET

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_GET — クエリストリング変数

### 説明

URL パラメータ (a.k.a クエリストリング) で現在のスクリプトに渡された変数の連想配列です。 この配列の値は、HTTP リクエストメソッドに関係なく、クエリストリングが含まれた全てのリクエストで収集されることに注意して下さい。

### 例

例1 $_GET の例

    <?php
    echo 'Hello ' . htmlspecialchars($_GET["name"]) . '!';
    ?>

ユーザーが `http://example.com/?name=Hannes` と入力したとします。

上の例の出力は、 たとえば以下のようになります。

    Hello Hannes!

### 注意

> 注意: これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

> 注意:

> $_GET の値は urldecode() 関数を介して自動的に渡されます。

### 参考

- 外部からくる変数の処理
- filter 拡張モジュール

# $_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; とする必要はありません。

> 注意: その他の content type (例: `application/json` や `application/xml`) を指定して送信された POST データを読み取るには、 php://input を使わなければいけません。 `application/x-www-form-urlencoded` と `multipart/form-data` を指定した場合にだけ動作する $_POST とは異なり、 php://input はリクエストボディの生データに直接アクセスします。

### 参考

- 外部からくる変数の処理
- filter 拡張モジュール

# $_FILES

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_FILES — HTTP ファイルアップロード変数

### 説明

HTTP POST メソッドで現在のスクリプトにアップロードされた項目の連想配列です。 この配列の構造については POST メソッドによるアップロード を参照ください。

### 注意

> 注意: これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

### 参考

- move_uploaded_file() - アップロードされたファイルを新しい位置に移動する
- ファイルアップロードの処理

# $_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 拡張モジュール

# $_SESSION

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

$_SESSION — セッション変数

### 説明

現在のスクリプトで使用できるセッション変数を含む連想配列です。 セッション変数の使用法についての詳細は、 セッション関数 のドキュメントを参照ください。

### 注意

> 注意: これは 'スーパーグローバル' あるいは自動グローバル変数と呼ばれるものです。 スクリプト全体を通してすべてのスコープで使用することができます。 関数やメソッドの内部で使用する場合にも global $variable; とする必要はありません。

### 参考

- session_start() - 新しいセッションを開始、あるいは既存のセッションを再開する

# $_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 拡張モジュール

# $_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 拡張モジュール

# $php_errormsg

(PHP 4, PHP 5, PHP 7)

$php_errormsg — 直近のエラーメッセージ

警告

この機能は PHP 7.2.0 で 非推奨 になり、PHP 8.0.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_response_header

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

$http_response_header — HTTP レスポンスヘッダ

警告

この機能は PHP 8.5.0 で 非推奨 になります。この機能に頼らないことを強く推奨します。

http_get_last_response_headers() を代わりに使ってください。

### 説明

$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=UTF-8"
    }

    Warning: Undefined variable $http_response_header
    NULL

### 参考

- http_get_last_response_headers() - 最後の HTTP レスポンスヘッダーを取得します
- http_clear_last_response_headers() - 保存された HTTP レスポンスヘッダーをクリア

# $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() - コマンドライン引数のリストからオプションを取得する
- $argv

# $argv

(PHP 4, PHP 5, PHP 7, PHP 8)

$argv — スクリプトに渡された引数の配列

### 説明

コマンドラインから実行したときに、 現在のスクリプトに渡されたすべての引数の配列が含まれます。

> 注意: 最初の引数 $argv[0] は常に、スクリプトの実行に使う名前となります。

> 注意: この変数は、register_argc_argv が無効になっている場合には使えません。

警告

スクリプトがコマンドラインから実行されているかどうかを確認するには、 $argv や $_SERVER['argv'] が設定されているかを確認するのではなく、php_sapi_name() を使うべきです。

### 例

例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() - コマンドライン引数のリストからオプションを取得する
- $argc

## 目次

- スーパーグローバル — すべてのスコープで使用できる組み込みの変数
- $GLOBALS — グローバルスコープで使用可能なすべての変数への参照
- $_SERVER — サーバー情報および実行時の環境情報
- $_GET — クエリストリング変数
- $_POST — HTTP POST リクエストから得られるフォームデータ
- $_FILES — HTTP ファイルアップロード変数
- $_REQUEST — HTTP リクエスト変数
- $_SESSION — セッション変数
- $_ENV — 環境変数
- $_COOKIE — HTTP クッキー
- $php_errormsg — 直近のエラーメッセージ
- $http_response_header — HTTP レスポンスヘッダ
- $argc — スクリプトに渡された引数の数
- $argv — スクリプトに渡された引数の配列

# 定義済みの例外

## 目次

- Exception
- ErrorException
- ClosedGeneratorException
- Error
- ArgumentCountError
- ArithmeticError
- AssertionError
- DivisionByZeroError
- CompileError
- ParseError
- TypeError
- ValueError
- UnhandledMatchError
- FiberError
- RequestParseBodyException

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 function __construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function getMessage(): string
final public function getPrevious(): ?Throwable
final public function getCode(): int
final public function getFile(): string
final public function getLine(): int
final public function getTrace(): array
final public function getTraceAsString(): string
public function __toString(): string
private function __clone(): void
}

## プロパティ

message

  例外メッセージ

code

  例外コード

file

  例外が作られたファイル名

line

  例外が作られた行

previous

  直前にスローされた例外

string

  スタックトレースを示す文字列

trace

  スタックトレースを示す配列

# Exception::__construct

(PHP 5, PHP 7, PHP 8)

Exception::__construct — 例外を作成する

### 説明

public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)

例外を作成します。

### パラメータ

`message`

  スローする例外メッセージ。

`code`

  例外コード。

`previous`

  以前に使われた例外。例外の連結に使用します。

> 注意: Exception クラスのコンストラクタをサブクラス側から呼ぶと、 $code と $message が設定済みの場合はデフォルトの引数を無視します。

### 注意

> 注意:

> `message` は、バイナリセーフ ではありません。

# Exception::getMessage

(PHP 5, PHP 7, PHP 8)

Exception::getMessage — 例外メッセージを取得する

### 説明

final public function 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() - メッセージを取得する

# Exception::getPrevious

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Exception::getPrevious — 前の例外(Throwable)を返す

### 説明

final public function 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::getCode

(PHP 5, PHP 7, PHP 8)

Exception::getCode — 例外コードを取得する

### 説明

final public function 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::getFile

(PHP 5, PHP 7, PHP 8)

Exception::getFile — 例外が作られたファイルを取得する

### 説明

final public function 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::getLine

(PHP 5, PHP 7, PHP 8)

Exception::getLine — 例外が作られた行を取得する

### 説明

final public function 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::getTrace

(PHP 5, PHP 7, PHP 8)

Exception::getTrace — スタックトレースを取得する

### 説明

final public function 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::getTraceAsString

(PHP 5, PHP 7, PHP 8)

Exception::getTraceAsString — スタックトレースを文字列で取得する

### 説明

final public function 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::__toString

(PHP 5, PHP 7, PHP 8)

Exception::__toString — 例外の文字列表現

### 説明

public function 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::__clone

(PHP 5, PHP 7, PHP 8)

Exception::__clone — 例外をコピーする

### 説明

private function Exception::__clone(): void

Exception のコピーは作成できません。 作成しようとすると、Error がスローされます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

値を返しません。

### エラー / 例外

例外はクローン不可能です。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | Exception::__clone() は、 final ではなくなりました。

## 目次

- Exception::__construct — 例外を作成する
- Exception::getMessage — 例外メッセージを取得する
- Exception::getPrevious — 前の例外(Throwable)を返す
- Exception::getCode — 例外コードを取得する
- Exception::getFile — 例外が作られたファイルを取得する
- Exception::getLine — 例外が作られた行を取得する
- Exception::getTrace — スタックトレースを取得する
- Exception::getTraceAsString — スタックトレースを文字列で取得する
- Exception::__toString — 例外の文字列表現
- Exception::__clone — 例外をコピーする

# 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 function __construct(
string `$message` = "",
int `$code` = 0,
int `$severity` = `E_ERROR`,
?string `$filename` = `null`,
?int `$line` = `null`,
?Throwable `$previous` = `null`
)
final public function getSeverity(): int
/* 継承したメソッド */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function 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

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ErrorException::__construct — 例外を作成する

### 説明

public function 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::getSeverity

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

ErrorException::getSeverity — 例外の深刻度を取得する

### 説明

final public function 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)

## 目次

- ErrorException::__construct — 例外を作成する
- ErrorException::getSeverity — 例外の深刻度を取得する

# 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 function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function 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 function __construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function getMessage(): string
final public function getPrevious(): ?Throwable
final public function getCode(): int
final public function getFile(): string
final public function getLine(): int
final public function getTrace(): array
final public function getTraceAsString(): string
public function __toString(): string
private function __clone(): void
}

## プロパティ

message

  エラーメッセージ

code

  エラーコード

file

  エラーが発生したファイル名

line

  エラーが発生した行番号

previous

  直前にスローされた例外

string

  スタックトレースを示す文字列

trace

  スタックトレースを示す配列

# Error::__construct

(PHP 7, PHP 8)

Error::__construct — エラーオブジェクトを生成する

### 説明

public function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)

エラーを生成する。

### パラメータ

`message`

  エラーメッセージ。

`code`

  エラーコード。

`previous`

  例外チェーンに使われる、直前のスロー可能オブジェクト。

### 注意

> 注意:

> `message` はバイナリセーフでは ありません。

# Error::getMessage

(PHP 7, PHP 8)

Error::getMessage — エラーメッセージを取得する

### 説明

final public function 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() - メッセージを取得する

# Error::getPrevious

(PHP 7, PHP 8)

Error::getPrevious — 直前の Throwable を返す

### 説明

final public function 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::getCode

(PHP 7, PHP 8)

Error::getCode — エラーコードを取得する

### 説明

final public function 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::getFile

(PHP 7, PHP 8)

Error::getFile — エラーが起きたファイルを取得する

### 説明

final public function 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::getLine

(PHP 7, PHP 8)

Error::getLine — エラーが起きた行番号を取得する

### 説明

final public function 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::getTrace

(PHP 7, PHP 8)

Error::getTrace — スタックトレースを取得する

### 説明

final public function 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::getTraceAsString

(PHP 7, PHP 8)

Error::getTraceAsString — スタックトレースを文字列として取得する

### 説明

final public function 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::__toString

(PHP 7, PHP 8)

Error::__toString — エラーの文字列表現

### 説明

public function 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::__clone

(PHP 7, PHP 8)

Error::__clone — エラーをクローンする

### 説明

private function Error::__clone(): void

エラーはクローンできないので、このメソッドは 致命的なエラーとなります。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

値を返しません。

### エラー / 例外

エラーはクローン可能ではありません。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | Error::__clone() は、 final ではなくなりました。

## 目次

- Error::__construct — エラーオブジェクトを生成する
- Error::getMessage — エラーメッセージを取得する
- Error::getPrevious — 直前の Throwable を返す
- Error::getCode — エラーコードを取得する
- Error::getFile — エラーが起きたファイルを取得する
- Error::getLine — エラーが起きた行番号を取得する
- Error::getTrace — スタックトレースを取得する
- Error::getTraceAsString — スタックトレースを文字列として取得する
- Error::__toString — エラーの文字列表現
- Error::__clone — エラーをクローンする

# 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 function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function 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 function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function 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 function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function 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 function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function 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 function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function 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 function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function 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 function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

## 変更履歴

バージョン | 説明
--- | ---
7.1.0 | strict モードの場合に、 PHP の組み込みの関数に渡す引数の数を間違えた場合でも、 TypeError はスローされなくなりました。 代わりに、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 function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function 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 function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function 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 function __construct()
/* 継承したメソッド */
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# FiberError::__construct

(PHP 8 >= 8.1.0)

FiberError::__construct — インスタンス化を禁止するためのコンストラクタ

### 説明

public function FiberError::__construct()

### パラメータ

この関数にはパラメータはありません。

### エラー / 例外

このメソッドがコールされると、 Error 例外がスローされます。

## 目次

- FiberError::__construct — インスタンス化を禁止するためのコンストラクタ

# RequestParseBodyException

(PHP 8 >= 8.4.0)

## はじめに

RequestParseBodyException は、 request_parse_body() 内でリクエストボディが無効な場合にスローされます。 これは、 `Content-Type` ヘッダーに基づいて判断されます。

## クラス概要

class RequestParseBodyException 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 function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# 定義済みのインターフェイスとクラス

## 目次

- Traversable
- Iterator
- IteratorAggregate
- InternalIterator
- Throwable
- Countable
- 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 function current(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function 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

(PHP 5, PHP 7, PHP 8)

Iterator::current — 現在の要素を返す

### 説明

public function Iterator::current(): mixed

現在の要素を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

あらゆる型を返すことが可能です。

# Iterator::key

(PHP 5, PHP 7, PHP 8)

Iterator::key — 現在の要素のキーを返す

### 説明

public function Iterator::key(): mixed

現在の要素のキーを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合にスカラー型、失敗した場合に `null` を返します。

### エラー / 例外

失敗した場合に `E_NOTICE` を発行します。

# Iterator::next

(PHP 5, PHP 7, PHP 8)

Iterator::next — 次の要素に進む

### 説明

public function Iterator::next(): void

現在位置を次の要素に移動します。

> 注意:

> このメソッドは、各 `foreach` ループの 後 にコールされます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

戻り値は無視されます。

# Iterator::rewind

(PHP 5, PHP 7, PHP 8)

Iterator::rewind — イテレータの最初の要素に巻き戻す

### 説明

public function Iterator::rewind(): void

イテレータの最初の要素に巻き戻します。

> 注意:

> これは、`foreach` ループの開始時に 最初 にコールされるメソッドです。 `foreach` ループの 後 には実行 されません。

> `foreach` は反復処理の開始前に必ず rewind() を呼び出すため、 手動でイテレータの位置を進めていた場合（例えば SplFileObject::seek() を使って移動した場合など）でもリセットされます。 巻き戻しを行わずに反復処理を行うには、 NoRewindIterator でラップしてください。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

戻り値は無視されます。

# Iterator::valid

(PHP 5, PHP 7, PHP 8)

Iterator::valid — 現在位置が有効かどうかを調べる

### 説明

public function Iterator::valid(): bool

このメソッドは Iterator::rewind() および Iterator::next() の後にコールされ、 現在の位置が有効かどうかを調べます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

戻り値は bool にキャストして評価されます。 成功した場合に `true` を、失敗した場合に `false` を返します。

## 目次

- Iterator::current — 現在の要素を返す
- Iterator::key — 現在の要素のキーを返す
- Iterator::next — 次の要素に進む
- Iterator::rewind — イテレータの最初の要素に巻き戻す
- Iterator::valid — 現在位置が有効かどうかを調べる

# IteratorAggregate インターフェイス

(PHP 5, PHP 7, PHP 8)

## はじめに

外部イテレータを作成するためのインターフェイスです。

## インターフェイス概要

interface IteratorAggregate extends Traversable {
/* メソッド */
public function getIterator(): Traversable
}

## 例

例1 基本的な使用法

    <?php

    class myData implements IteratorAggregate
    {
        public function getIterator(): Traversable
        {
            return new ArrayIterator([
                "key one" => "item one",
                "key two" => "item two",
                "key three" => "item three"
            ]);
        }
    }

    $obj = new myData();

    foreach ($obj as $key => $value) {
        var_dump($key, $value);
        echo "\n";
    }

上の例の出力は、 たとえば以下のようになります。

    string(7) "key one"
    string(8) "item one"

    string(7) "key two"
    string(8) "item two"

    string(9) "key three"
    string(10) "item three"

# IteratorAggregate::getIterator

(PHP 5, PHP 7, PHP 8)

IteratorAggregate::getIterator — 外部イテレータ または traversable を取得する

### 説明

public function IteratorAggregate::getIterator(): Traversable

外部イテレータ または traversable を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Iterator あるいは Traversable を実装したオブジェクトのインスタンスを返します。

### エラー / 例外

失敗した場合は Exception をスローします。

## 目次

- IteratorAggregate::getIterator — 外部イテレータ または traversable を取得する

# InternalIterator クラス

(PHP 8)

## はじめに

内部クラス が、 IteratorAggregate を実装しやすくするためのクラスです。

## クラス概要

final class InternalIterator implements Iterator {
/* メソッド */
private function __construct()
public function current(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function valid(): bool
}

# InternalIterator::__construct

(PHP 8)

InternalIterator::__construct — private なコンストラクタのため、直接インスタンス化できません

### 説明

private function InternalIterator::__construct()

### パラメータ

この関数にはパラメータはありません。

# InternalIterator::current

(PHP 8)

InternalIterator::current — 現在の要素を返す

### 説明

public function InternalIterator::current(): mixed

現在の要素を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

現在の要素を返します。

# InternalIterator::key

(PHP 8)

InternalIterator::key — 現在の要素のキーを返す

### 説明

public function InternalIterator::key(): mixed

現在の要素のキーを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

現在の要素のキーを返します。

# InternalIterator::next

(PHP 8)

InternalIterator::next — 次の要素に進む

### 説明

public function InternalIterator::next(): void

現在位置を次の要素に移動します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

値を返しません。

# InternalIterator::rewind

(PHP 8)

InternalIterator::rewind — イテレータの最初の要素に巻き戻す

### 説明

public function InternalIterator::rewind(): void

イテレータの最初の要素に巻き戻します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

値を返しません。

# InternalIterator::valid

(PHP 8)

InternalIterator::valid — 現在位置が有効かどうかを調べる

### 説明

public function InternalIterator::valid(): bool

現在位置が有効かどうかを調べます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

現在位置が有効かどうかを返します。

## 目次

- InternalIterator::__construct — private なコンストラクタのため、直接インスタンス化できません
- InternalIterator::current — 現在の要素を返す
- InternalIterator::key — 現在の要素のキーを返す
- InternalIterator::next — 次の要素に進む
- InternalIterator::rewind — イテレータの最初の要素に巻き戻す
- InternalIterator::valid — 現在位置が有効かどうかを調べる

# Throwable

(PHP 7, PHP 8)

## はじめに

Throwable は、`throw` 文でスロー可能なあらゆるオブジェクトが実装する基底インターフェイスです。 Error や Exception も、これを実装しています。

> 注意:

> PHP のクラスが Throwable インターフェイスを直接実装することはできません。 そのかわりに、Exception を継承する必要があります。

## インターフェイス概要

interface Throwable extends Stringable {
/* メソッド */
public function getMessage(): string
public function getCode(): int
public function getFile(): string
public function getLine(): int
public function getTrace(): array
public function getTraceAsString(): string
public function getPrevious(): ?Throwable
public function __toString(): string
/* 継承したメソッド */
public function Stringable::__toString(): string
}

## 変更履歴

バージョン | 説明
--- | ---
8.0.0 | Throwable は、 Stringable を新たに実装しました。

# Throwable::getMessage

(PHP 7, PHP 8)

Throwable::getMessage — メッセージを取得する

### 説明

public function Throwable::getMessage(): string

スローされたオブジェクトに関連づけられたメッセージを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

スローされたオブジェクトに関連づけられたメッセージを返します。

### 参考

- Exception::getMessage() - 例外メッセージを取得する

# Throwable::getCode

(PHP 7, PHP 8)

Throwable::getCode — 例外コードを取得する

### 説明

public function Throwable::getCode(): int

スローされたオブジェクトのエラーコードを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

例外コードを返します。 Exception の場合は int ですが、 その派生クラスでは別の型かもしれません (たとえば PDOException の場合は string です)。

### 参考

- Exception::getCode() - 例外コードを取得する

# Throwable::getFile

(PHP 7, PHP 8)

Throwable::getFile — オブジェクトが作られたファイル名を取得する

### 説明

public function Throwable::getFile(): string

スローされたオブジェクトが作られたファイル名を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

スローされたオブジェクトが作られたファイル名を返します。

### 参考

- Exception::getFile() - 例外が作られたファイルを取得する

# Throwable::getLine

(PHP 7, PHP 8)

Throwable::getLine — オブジェクトのインスタンスが作られた行番号を取得する

### 説明

public function Throwable::getLine(): int

スローされたオブジェクトのインスタンスが作られた行番号を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

スローされたオブジェクトのインスタンスが作られた行番号を返します。

### 参考

- Exception::getLine() - 例外が作られた行を取得する

# Throwable::getTrace

(PHP 7, PHP 8)

Throwable::getTrace — スタックトレースを取得する

### 説明

public function Throwable::getTrace(): array

スタックトレースの配列を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

スタックトレースの配列を返します。その書式は debug_backtrace() と同じです。

### 参考

- Exception::getTrace() - スタックトレースを取得する

# Throwable::getTraceAsString

(PHP 7, PHP 8)

Throwable::getTraceAsString — スタックトレースを文字列として取得する

### 説明

public function Throwable::getTraceAsString(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

スタックトレースを文字列として返します。

### 参考

- Exception::getTraceAsString() - スタックトレースを文字列で取得する

# Throwable::getPrevious

(PHP 7, PHP 8)

Throwable::getPrevious — ひとつ前の Throwable を返す

### 説明

public function Throwable::getPrevious(): ?Throwable

ひとつ前の Throwable (たとえば Exception::__construct() の第三パラメータで指定したもの) を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

ひとつ前の Throwable が存在すればそれを返します。 存在しない場合は `null` を返します。

### 参考

- Exception::getPrevious() - 前の例外(Throwable)を返す

# Throwable::__toString

(PHP 7, PHP 8)

Throwable::__toString — スローされたオブジェクトの文字列表現を取得する

### 説明

public function Throwable::__toString(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

スローされたオブジェクトの文字列表現を返します。

### 参考

- Exception::__toString() - 例外の文字列表現

## 目次

- Throwable::getMessage — メッセージを取得する
- Throwable::getCode — 例外コードを取得する
- Throwable::getFile — オブジェクトが作られたファイル名を取得する
- Throwable::getLine — オブジェクトのインスタンスが作られた行番号を取得する
- Throwable::getTrace — スタックトレースを取得する
- Throwable::getTraceAsString — スタックトレースを文字列として取得する
- Throwable::getPrevious — ひとつ前の Throwable を返す
- Throwable::__toString — スローされたオブジェクトの文字列表現を取得する

# Countable インターフェイス

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

## はじめに

Countable を実装したクラスは、 count() 関数で使用することができます。

## インターフェイス概要

interface Countable {
/* メソッド */
public function count(): int
}

# Countable::count

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Countable::count — オブジェクトの要素の数を数える

### 説明

public function Countable::count(): int

このメソッドは、 count() 関数の `value` パラメーターが Countable を実装している場合に実行されます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

数えたカスタムの結果を整数値として返します。

### 例

例1 Countable::count() の例

    <?php

    class Counter implements Countable
    {
        private $count = 0;

        public function count(): int
        {
            return ++$this->count;
        }
    }

    $counter = new Counter;

    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

## 目次

- Countable::count — オブジェクトの要素の数を数える

# ArrayAccess インターフェイス

(PHP 5, PHP 7, PHP 8)

## はじめに

配列としてオブジェクトにアクセスするための機能のインターフェイスです。

## インターフェイス概要

interface ArrayAccess {
/* メソッド */
public function offsetExists(mixed `$offset`): bool
public function offsetGet(mixed `$offset`): mixed
public function offsetSet(mixed `$offset`, mixed `$value`): void
public function 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] => Array
            (
                [one] => 1
                [three] => 3
                [two] => A value
                [0] => Append 1
                [1] => Append 2
                [2] => Append 3
            )

    )

# ArrayAccess::offsetExists

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetExists — オフセットが存在するかどうか

### 説明

public function 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::offsetGet

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetGet — オフセットを取得する

### 説明

public function 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::offsetSet

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetSet — 指定したオフセットに値を設定する

### 説明

public function 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::offsetUnset

(PHP 5, PHP 7, PHP 8)

ArrayAccess::offsetUnset — オフセットの設定を解除する

### 説明

public function ArrayAccess::offsetUnset(mixed `$offset`): void

オフセットの設定を解除します。

> 注意:

> このメソッドは、 (unset) による型キャストの際にはコール されません。

### パラメータ

`offset`

  設定解除したいオフセット。

### 戻り値

値を返しません。

## 目次

- ArrayAccess::offsetExists — オフセットが存在するかどうか
- ArrayAccess::offsetGet — オフセットを取得する
- ArrayAccess::offsetSet — 指定したオフセットに値を設定する
- ArrayAccess::offsetUnset — オフセットの設定を解除する

# 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 function serialize(): ?string
public function 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());
    ?>

上の例の出力は、 たとえば以下のようになります。

    Deprecated: obj implements the Serializable interface, which is deprecated. Implement __serialize() and __unserialize() instead (or in addition, if support for old PHP versions is necessary) in script on line 2
    string(38) "C:3:"obj":23:{s:15:"My private data";}"
    string(15) "My private data"

# Serializable::serialize

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Serializable::serialize — オブジェクトの文字列表現

### 説明

public function Serializable::serialize(): ?string

オブジェクトを文字列であらわしたものを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

オブジェクトの文字列表現、あるいは `null` を返します。

### エラー / 例外

文字列や `null` 以外の型を返すときに Exception をスローします。

### 参考

- __sleep()
- __serialize()

# Serializable::unserialize

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

Serializable::unserialize — オブジェクトを作成する

### 説明

public function Serializable::unserialize(string `$data`): void

オブジェクトのアンシリアライズ時にコールされます。

> 注意:

> このメソッドは、オブジェクトの コンストラクタ として働きます。 このメソッドの後に __construct() メソッドがコールされることは ありません。

### パラメータ

`data`

  オブジェクトの文字列表現。

### 戻り値

このメソッドの戻り値は無視されます。

### 参考

- __wakeup()
- __unserialize()

## 目次

- Serializable::serialize — オブジェクトの文字列表現
- Serializable::unserialize — オブジェクトを作成する

# Closure クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## はじめに

無名関数 を表すために使うクラスです。

無名関数は、Closure 型のオブジェクトを生成します。 このクラスにはメソッドが用意され、 生成した無名関数をさらにコントロールできるようになっています。

ここであげたメソッド以外にも、このクラスには `__invoke` メソッドが存在します。 これは、マジックメソッド __invoke() を実装した他のクラスとの一貫性を保つためのものであり、 関数をコールするときにこのメソッドは使われません。

## クラス概要

final class Closure {
/* メソッド */
private function __construct()
public static function bind(Closure `$closure`, ?object `$newThis`, object|string|null `$newScope` = "static"): ?Closure
public function bindTo(?object `$newThis`, object|string|null `$newScope` = "static"): ?Closure
public function call(object `$newThis`, mixed `...$args`): mixed
public static function fromCallable(callable `$callback`): Closure
public static function getCurrent(): Closure
}

## 変更履歴

バージョン | 説明
--- | ---
8.4.0 | Closure::__debugInfo() の出力に、 クロージャの名前、行、ファイルを含むようになりました。

## 注意

> 注意: Closure オブジェクトはシリアライズできません。 クロージャは束縛された変数や特定の実行コンテキストを保持している可能性があるためです。 クロージャをシリアライズしようとすると、Exception がスローされます。

# Closure::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Closure::__construct — インスタンス作成を無効化したコンストラクタ

### 説明

private function Closure::__construct()

このメソッドは、 Closure クラスのインスタンスを作れないようにするために存在します。 このクラスのオブジェクトを作るには、 無名関数 のページに書かれている手順を使います。

### パラメータ

この関数にはパラメータはありません。

### 参考

- 無名関数

# Closure::bind

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

Closure::bind — バインドされたオブジェクトとクラスのスコープでクロージャを複製する

### 説明

public static function 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::bindTo

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

Closure::bindTo — 新しくバインドしたオブジェクトとクラスのスコープで、クロージャを複製する

### 説明

public function 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::call

(PHP 7, PHP 8)

Closure::call — クロージャを束縛して呼び出す

### 説明

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

# Closure::fromCallable

(PHP 7 >= 7.1.0)

Closure::fromCallable — callable をクロージャに変換する

### 説明

public static function Closure::fromCallable(callable `$callback`): Closure

現在のスコープを用いて、指定された `callback` から新しい 無名関数 を作って返します。 このメソッドは、現在のスコープで `callback` が呼び出し可能かどうかをチェックし、可能でなければ TypeError をスローします。

> 注意:

> PHP 8.1.0 以降では、このメソッドと同等の機能を実現するやり方として、第一級callableを生成する記法 があります。

### パラメータ

`callback`

  変換する callable。

### 戻り値

新しく作られた Closure を返します。 `callback` が現在のスコープで呼び出し可能でなければ、 TypeError をスローします。

### 参考

- 無名関数
- 第一級callableを生成する記法

# Closure::getCurrent

(PHP 8 >= 8.5.0)

Closure::getCurrent — 現在実行中のクロージャを返す

### 説明

public static function Closure::getCurrent(): Closure

現在実行中のクロージャを返します。このメソッドは主に、 `use` キーワードを使ってクロージャ変数への参照をキャプチャすることなく、 再帰的なクロージャを実装するのに役立ちます。

このメソッドはクロージャの内部から呼び出す必要があります。 クロージャのコンテキスト外から呼び出すと、 `Error: Current function is not a closure.` が発生します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

現在実行中の Closure を返します。

### エラー / 例外

クロージャのコンテキスト外から呼び出された場合、 Error をスローします。

### 例

例1 Closure::getCurrent() の例

Closure::getCurrent() を使って 再帰的なフィボナッチ関数を実装する例:

    <?php
    $fibonacci = function (int $n) {
        if ($n === 0 || $n === 1) {
            return $n;
        }

        $fn = Closure::getCurrent();
        return $fn($n - 1) + $fn($n - 2);
    };

    echo $fibonacci(10); // 出力: 55
    ?>

例2 従来のアプローチとの比較

PHP 8.5 より前のバージョンでは、再帰的なクロージャを実装するには `use` キーワードを使ってクロージャ変数への参照をキャプチャする必要がありました:

    <?php
    // 従来のアプローチ (PHP 8.5 でも引き続き使用可能)
    $fibonacci = function (int $n) use (&$fibonacci) {
        if ($n === 0) return 0;
        if ($n === 1) return 1;
        return $fibonacci($n - 1) + $fibonacci($n - 2);
    };

    echo $fibonacci(10); // 出力: 55
    ?>

Closure::getCurrent() を使うアプローチでは、 `use` 句で変数を参照で宣言する必要がなくなり、 コードがよりクリーンで間違いにくくなります。

## 目次

- Closure::__construct — インスタンス作成を無効化したコンストラクタ
- Closure::bind — バインドされたオブジェクトとクラスのスコープでクロージャを複製する
- Closure::bindTo — 新しくバインドしたオブジェクトとクラスのスコープで、クロージャを複製する
- Closure::call — クロージャを束縛して呼び出す
- Closure::fromCallable — callable をクロージャに変換する
- Closure::getCurrent — 現在実行中のクロージャを返す

# stdClass クラス

(PHP 4, PHP 5, PHP 7, PHP 8)

## はじめに

動的なプロパティが使える、汎用的な空のクラスです。

このクラスのインスタンスは、 new 演算子や、 オブジェクトへの型変換 によって作成できます。 PHP の関数によっては、このクラスのインスタンスを返すものがあります。 たとえば json_decode(), mysqli_fetch_object(), PDOStatement::fetchObject() が挙げられます。

マジックメソッド __get()/__set() を実装しているかどうかに関わらず、 このクラスでは動的なプロパティが許可されています。 よって、`#[\AllowDynamicProperties]` アトリビュートは必要ありません。

PHP には全てのクラスの親となる基底クラスの概念がないため、 このクラスは基底クラスではありません。 ただ、stdClass を継承させることで、 動的なプロパティの機能を持ったカスタムクラスを結果的に作ることはできます。

## クラス概要

#[\AllowDynamicProperties]
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 function current(): mixed
public function getReturn(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function send(mixed `$value`): mixed
public function throw(Throwable `$exception`): mixed
public function valid(): bool
public function __wakeup(): void
}

## 参考

オブジェクトの反復処理 も参照ください。

# Generator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::current — yield した値を取得する

### 説明

public function Generator::current(): mixed

### パラメータ

この関数にはパラメータはありません。

### 戻り値

yield した値を返します。

# Generator::getReturn

(PHP 7, PHP 8)

Generator::getReturn — ジェネレータの戻り値を取得する

### 説明

public function 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

# Generator::key

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::key — yield したキーを取得する

### 説明

public function Generator::key(): mixed

yield した値のキーを取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

yield したキーを返します。

### 例

例1 Generator::key() の例

    <?php

    function Gen()
    {
        yield 'key' => 'value';
    }

    $gen = Gen();

    echo "{$gen->key()} => {$gen->current()}";

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

    key => value

# Generator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::next — ジェネレータを続行する

### 説明

public function Generator::next(): void

Generator::next() のコールは、 `null` を引数として Generator::send() をコールすることと同じ効果があります。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

値を返しません。

# Generator::rewind

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::rewind — 最初の yield までジェネレータを実行する

### 説明

public function Generator::rewind(): void

最初の `yield` までジェネレーターを実行します。 ジェネレーターが既に 最初の `yield` に到達している場合、 何も行いません。 ジェネレーターが `yield` 式を越えて進んでいる場合、 このメソッドは Exception をスローします。

> 注意:

> これは、`foreach` ループを開始する際に 最初に コールされるメソッドです。`foreach` ループが実行された 後に 実行されるのでは ありません。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

値を返しません。

### 例

例1 Generator::rewind() の例

    <?php

    function generator(): Generator
    {
        echo "I'm a generator!\n";

        for ($i = 1; $i <= 3; $i++) {
            yield $i;
        }
    }

    // ジェネレータを初期化
    $generator = generator();

    // まだ達していない場合、最初の yield 式の開始までジェネレータを巻き戻します。
    $generator->rewind(); // I'm a generator!

    // ここでは何も起きません; ジェネレータは既に巻き戻されています。
    $generator->rewind(); // No output (NULL)

    // ここでは、まだ達していない場合、
    // 最初の yield 式の開始までジェネレータを巻き戻します。
    // そして、ジェネレータを反復します。
    foreach ($generator as $value) {
        // 最初の値を yield したあと、ジェネレータは
        // 実行が再開されて次の yield に進むまで最初の
        // yield 式にとどまったままです。
        echo $value, PHP_EOL; // 1

        break;
    }

    // 巻き戻しを再開します。
    // エラーは発生しません。なぜんら、ジェネレータは最初の yield を越えて
    // 進んでいないからです。
    $generator->rewind();

    echo $generator->current(), PHP_EOL; // 1

    // エラーは起きません。
    // ジェネレータはまだ最初の yield に留まっています。
    $generator->rewind();

    // ここで、ジェネレータを二回目の yield 式に進めます。
    $generator->next();

    try {
        // これは、例外をスローします。
        // なぜなら、既にジェネレータが二回目の yield に進んでいるからです。
        $generator->rewind(); // Fatal error: Uncaught Exception: Cannot rewind a generator that was already run
    } catch (Exception $e) {
        echo $e->getMessage();
    }

    ?>

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

    I'm a generator!
    1
    1
    Cannot rewind a generator that was already run

# Generator::send

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::send — 値をジェネレータに送る

### 説明

public function 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::throw

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::throw — 例外をジェネレータにスローする

### 説明

public function 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::valid

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::valid — イテレータが終了したかどうかを調べる

### 説明

public function Generator::valid(): bool

### パラメータ

この関数にはパラメータはありません。

### 戻り値

イテレータが終了した場合に `false` を返します。まだ終了していない場合は `true` を返します。

# Generator::__wakeup

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

Generator::__wakeup — シリアライズのコールバック

### 説明

public function Generator::__wakeup(): void

ジェネレータはシリアライズできないので、例外をスローします。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

値を返しません。

## 目次

- Generator::current — yield した値を取得する
- Generator::getReturn — ジェネレータの戻り値を取得する
- Generator::key — yield したキーを取得する
- Generator::next — ジェネレータを続行する
- Generator::rewind — 最初の yield までジェネレータを実行する
- Generator::send — 値をジェネレータに送る
- Generator::throw — 例外をジェネレータにスローする
- Generator::valid — イテレータが終了したかどうかを調べる
- Generator::__wakeup — シリアライズのコールバック

# Fiber クラス

(PHP 8 >= 8.1.0)

## はじめに

ファイバー(Fiber) は 完全なスタックを持つ、停止可能な関数です。 ファイバー はコールスタック中のどこからでも停止することができますし、 後に再開されるまで実行を停止したままにできます。

## クラス概要

final class Fiber {
/* メソッド */
public function __construct(callable `$callback`)
public function start(mixed `...$args`): mixed
public function resume(mixed `$value` = `null`): mixed
public function throw(Throwable `$exception`): mixed
public function getReturn(): mixed
public function isStarted(): bool
public function isSuspended(): bool
public function isRunning(): bool
public function isTerminated(): bool
public static function suspend(mixed `$value` = `null`): mixed
public static function getCurrent(): ?Fiber
}

## 参考

ファイバーの概要

# Fiber::__construct

(PHP 8 >= 8.1.0)

Fiber::__construct — 新しいファイバーのインスタンスを構築する

### 説明

public function Fiber::__construct(callable `$callback`)

### パラメータ

`callback`

  ファイバーを開始する時の callable を指定します。 Fiber::start() に引数を指定することで、 ここで指定する callable に引数を与えます。

# Fiber::start

(PHP 8 >= 8.1.0)

Fiber::start — ファイバーの実行を開始する

### 説明

public function Fiber::start(mixed `...$args`): mixed

ファイバーを構築する際に使われる callable に対して、可変長引数を指定します。

このメソッドをコールした時点で ファイバーが既に開始されている場合、 FiberError がスローされます。

### パラメータ

`args`

  ファイバーのコンストラクタに指定する callable を呼び出す際に、 使用する引数。

### 戻り値

Fiber::suspend() が最初にコールされた際に指定した値を返します。 ファイバーから制御が戻った場合は `null` を返します。 停止する前に ファイバーが例外をスローする場合、 このメソッドの呼び出しからスローされます。

# Fiber::resume

(PHP 8 >= 8.1.0)

Fiber::resume — 値を渡して、ファイバーの実行を再開させる

### 説明

public function Fiber::resume(mixed `$value` = `null`): mixed

現在の Fiber::suspend() の呼び出し結果として、指定した値を渡すことでファイバーを再開します。

このメソッドがコールされた時点で ファイバーが停止していない場合、 FiberError がスローされます。

### パラメータ

`value`

  ファイバーの実行を再開するための値。 この値は、 現在の Fiber::suspend() からの戻り値となります。

### 戻り値

Fiber::suspend() が次回コールされた際に指定した値を返します。 ファイバーから制御が戻った場合は `null` を返します。 停止する前に ファイバーが例外をスローする場合、 このメソッドの呼び出しからスローされます。

# Fiber::throw

(PHP 8 >= 8.1.0)

Fiber::throw — ファイバーの実行を、例外をスローすることで再開する

### 説明

public function Fiber::throw(Throwable `$exception`): mixed

現在の Fiber::suspend() への呼び出しから、 指定した例外をスローさせることでファイバーを再開させます。

このメソッドがコールされた時点でファイバーが停止していない場合、 FiberError がスローされます。

### パラメータ

`exception`

  現在の Fiber::suspend() への呼び出しから、 ファイバーにスローする例外を指定します。

### 戻り値

Fiber::suspend() が次回コールされた際に指定した値を返します。 ファイバーから制御が戻った場合は `null` を返します。 停止する前にファイバーが例外をスローする場合、 このメソッドの呼び出しからスローされます。

### 例

    <?php

    $fiber = new Fiber(function () {
       try {
           // 中断ポイントを宣言してファイバーの実行を停止する
           Fiber::suspend();
       } catch (Throwable $e) {
           echo $e->getMessage();
       }
    });

    $fiber->start();

    // 中断ポイントでスローする例外を渡して
    // ファイバーの実行を再開する
    $fiber->throw(new Exception('Message of an exception thrown at the current interrupt point'));

    ?>

上の例の出力は、 たとえば以下のようになります。

    Message of an exception thrown at the current interrupt point

# Fiber::getReturn

(PHP 8 >= 8.1.0)

Fiber::getReturn — ファイバーが返した値を取得する

### 説明

public function Fiber::getReturn(): mixed

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Fiber::__construct() に指定した callable が返した値を返します。 ファイバーが値を返さなかった場合、 ファイバーそのものが開始されていないか、 終了していないか、例外をスローしている場合で、 それらの場合は FiberError がスローされます。

# Fiber::isStarted

(PHP 8 >= 8.1.0)

Fiber::isStarted — ファイバーが開始したかどうかを調べる

### 説明

public function Fiber::isStarted(): bool

### パラメータ

この関数にはパラメータはありません。

### 戻り値

ファイバーが既に開始した後にのみ、 `true` を返します。 そうでない場合、`false` を返します。

# Fiber::isSuspended

(PHP 8 >= 8.1.0)

Fiber::isSuspended — ファイバーが停止中かどうかを調べる

### 説明

public function Fiber::isSuspended(): bool

### パラメータ

この関数にはパラメータはありません。

### 戻り値

ファイバーが現在停止中の場合に `true` を返します。 そうでない場合、`false` を返します。

# Fiber::isRunning

(PHP 8 >= 8.1.0)

Fiber::isRunning — ファイバーが実行中かどうかを調べる

### 説明

public function Fiber::isRunning(): bool

### パラメータ

この関数にはパラメータはありません。

### 戻り値

ファイバーが実行中の場合にのみ `true` を返します。 Fiber::start(), Fiber::resume(), Fiber::throw() のいずれかがコールされた (但し、Fiber::throw の場合は、まだ制御が戻っていない場合に限る) 後、 ファイバーは実行中と見なされます。 ファイバーが実行中でない場合、`false` を返します。

# Fiber::isTerminated

(PHP 8 >= 8.1.0)

Fiber::isTerminated — ファイバーが終了しているかを調べる

### 説明

public function Fiber::isTerminated(): bool

### パラメータ

この関数にはパラメータはありません。

### 戻り値

ファイバーが終了した後にのみ、`true` を返します。 値を返したか、例外をスローした場合のいずれかに限ります。 そうでない場合、`false` を返します。

# Fiber::suspend

(PHP 8 >= 8.1.0)

Fiber::suspend — 現在実行中のファイバーを停止する

### 説明

public static function 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::getCurrent

(PHP 8 >= 8.1.0)

Fiber::getCurrent — 現在実行中のファイバーのインスタンスを取得する

### 説明

public static function Fiber::getCurrent(): ?Fiber

### パラメータ

この関数にはパラメータはありません。

### 戻り値

現在実行中の Fiber のインスタンスを返します。 このメソッドがファイバーの外から実行された場合は `null` を返します。

## 目次

- Fiber::__construct — 新しいファイバーのインスタンスを構築する
- Fiber::start — ファイバーの実行を開始する
- Fiber::resume — 値を渡して、ファイバーの実行を再開させる
- Fiber::throw — ファイバーの実行を、例外をスローすることで再開する
- Fiber::getReturn — ファイバーが返した値を取得する
- Fiber::isStarted — ファイバーが開始したかどうかを調べる
- Fiber::isSuspended — ファイバーが停止中かどうかを調べる
- Fiber::isRunning — ファイバーが実行中かどうかを調べる
- Fiber::isTerminated — ファイバーが終了しているかを調べる
- Fiber::suspend — 現在実行中のファイバーを停止する
- Fiber::getCurrent — 現在実行中のファイバーのインスタンスを取得する

# WeakReference クラス

(PHP 7 >= 7.4.0, PHP 8)

## はじめに

弱い参照により、オブジェクトが破棄されるのを妨げないオブジェクトへの参照を保持することが可能です。 この機能は、キャッシュのようなデータ構造を実装するのに役立ちます。 元のオブジェクトが破棄されている場合、WeakReference::get() メソッドを呼び出すと `null` を返します。 元のオブジェクトは、refcount が 0 になると破棄されます。 弱い参照を作成しても、参照されているオブジェクトの `refcount` は増加しません。

WeakReference クラスはシリアライズできません。

## クラス概要

final class WeakReference {
/* メソッド */
public function __construct()
public static function create(object `$object`): WeakReference
public function 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

## 変更履歴

バージョン | 説明
--- | ---
8.4.0 | WeakReference::__debugInfo() の出力に、 参照されたオブジェクトを含むようになりました。また、参照が有効ではなくなっている場合は、 参照されたオブジェクトは `NULL` となります。

# WeakReference::__construct

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::__construct — コンストラクタを使ってインスタンス化はできません

### 説明

public function WeakReference::__construct()

このメソッドは、WeakReference クラスの インスタンス化を禁止するためだけに存在しています。 WeakReference は、 ファクトリメソッド WeakReference::create() を使ってインスタンス化されることになっています。

### パラメータ

この関数にはパラメータはありません。

### 参考

- WeakReference::create() - 弱い参照を生成する

# WeakReference::create

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::create — 弱い参照を生成する

### 説明

public static function WeakReference::create(object `$object`): WeakReference

新しい WeakReference を生成します

### パラメータ

`object`

  このオブジェクトは、弱く参照されます。

### 戻り値

新しい WeakReference を返します。 既に同じオブジェクトに対する WeakReference のインスタンスが存在する場合は、それを返します。

# WeakReference::get

(PHP 7 >= 7.4.0, PHP 8)

WeakReference::get — 弱く参照されたオブジェクトを取得する

### 説明

public function WeakReference::get(): ?object

弱く参照されたオブジェクトを取得します。 既にオブジェクトが破棄されていた場合、`null` が返されます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

参照されている object を返します。 オブジェクトが破棄されている場合は、`null` を返します。

## 目次

- WeakReference::__construct — コンストラクタを使ってインスタンス化はできません
- WeakReference::create — 弱い参照を生成する
- WeakReference::get — 弱く参照されたオブジェクトを取得する

# WeakMap クラス

(PHP 8)

## はじめに

WeakMap は、 オブジェクトをキーとして受け入れるマップ(辞書)です。 SplObjectStorage と似ていますが、 WeakMap のキーとなるオブジェクトは、 オブジェクトのリファレンスカウントが更新されません。 つまり、WeakMap のキーとなっているオブジェクトだけが唯一の残された参照だった場合、 オブジェクトはガベージコレクションの対象となり WeakMap から削除されます。 WeakMap の用途は、 長く生き残る必要がないオブジェクトから派生した、 データのキャッシュを作ることです。

WeakMap は ArrayAccess, Traversable (IteratorAggregate 経由), Countable を実装しています。 よって、ほとんどのケースで、 連想配列と同じやり方で操作できます。

## クラス概要

final class WeakMap implements ArrayAccess, Countable, IteratorAggregate {
/* メソッド */
public function count(): int
public function getIterator(): Iterator
public function offsetExists(object `$object`): bool
public function offsetGet(object `$object`): mixed
public function offsetSet(object `$object`, mixed `$value`): void
public function 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

(PHP 8)

WeakMap::count — マップ内に存在する有効なエントリの数を数える

### 説明

public function WeakMap::count(): int

マップ内の有効なエントリの数を数えます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

マップ内の有効なエントリの数を返します。

# WeakMap::getIterator

(PHP 8)

WeakMap::getIterator — イテレータを取得する

### 説明

public function WeakMap::getIterator(): Iterator

イテレータを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Iterator または Traversable を実装したオブジェクトのインスタンスを返します。

### エラー / 例外

失敗した場合は Exception をスローします。

# WeakMap::offsetExists

(PHP 8)

WeakMap::offsetExists — あるオブジェクトがマップ内に存在するかを調べる

### 説明

public function WeakMap::offsetExists(object `$object`): bool

指定されたオブジェクトが、マップ内で参照されているかを調べます。

### パラメータ

`object`

  チェックするオブジェクト

### 戻り値

オブジェクトがマップ内に含まれている場合、`true` を返します。 そうでない場合、`false` を返します。

# WeakMap::offsetGet

(PHP 8)

WeakMap::offsetGet — オブジェクトが指す値を返す

### 説明

public function WeakMap::offsetGet(object `$object`): mixed

指定されたオブジェクトが指す値を返します。

### パラメータ

`object`

  マップにキーとして含まれるオブジェクト

### 戻り値

引数で渡されたオブジェクトに関連付けられた値を返します。

### エラー / 例外

失敗した場合、Error をスローします。

# WeakMap::offsetSet

(PHP 8)

WeakMap::offsetSet — 新しいキーと値でマップを更新する

### 説明

public function WeakMap::offsetSet(object `$object`, mixed `$value`): void

新しいキーと値でマップを更新します。 既にキーがマップに存在した場合、古い値は新しい値で置き換えられます。

### パラメータ

`object`

  キーと値のペアを構成する、キーとなるオブジェクト

`value`

  キーと値のペアのうち、値となる任意のデータ

### 戻り値

値を返しません。

# WeakMap::offsetUnset

(PHP 8)

WeakMap::offsetUnset — マップからエントリを削除する

### 説明

public function WeakMap::offsetUnset(object `$object`): void

マップからエントリを削除します。

### パラメータ

`object`

  マップから削除するオブジェクト

### 戻り値

値を返しません。

## 目次

- WeakMap::count — マップ内に存在する有効なエントリの数を数える
- WeakMap::getIterator — イテレータを取得する
- WeakMap::offsetExists — あるオブジェクトがマップ内に存在するかを調べる
- WeakMap::offsetGet — オブジェクトが指す値を返す
- WeakMap::offsetSet — 新しいキーと値でマップを更新する
- WeakMap::offsetUnset — マップからエントリを削除する

# Stringable インターフェイス

(PHP 8)

## はじめに

Stringable インターフェイスは、 特定のクラスが __toString() メソッドを実装していることを示します。 ほとんどのインターフェイスと異なり、 Stringable は、マジックメソッド __toString() が定義されているあらゆるクラスで 暗黙のうちに存在すると見なされますが、 明示的に宣言することもできますし、宣言すべきです。

このインターフェイスの一番の存在意義は、 文字列プリミティブや、 文字列にキャストできるオブジェクトを受け入れる union型 `string|Stringable` に対する型チェックを、関数ができるようにすることです。

## インターフェイス概要

interface Stringable {
/* メソッド */
public function __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

(PHP 8)

Stringable::__toString — オブジェクトの文字列表現を取得する

### 説明

public function Stringable::__toString(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

オブジェクトの文字列表現を返します。

### 参考

- __toString()

## 目次

- Stringable::__toString — オブジェクトの文字列表現を取得する

# UnitEnum インターフェイス

(PHP 8 >= 8.1.0)

## はじめに

UnitEnum インターフェイスは、 全ての列挙型に対して、PHP のエンジンが自動的に適用するものです。 ユーザー定義のクラスとして実装してはいけません。 列挙型はメソッドのオーバーライドを禁止しています。 デフォルトの実装は PHP のエンジンから提供されるからです。 このインターフェイスは、型チェックのためだけに存在しています。

## インターフェイス概要

interface UnitEnum {
/* メソッド */
public static function cases(): array
}

# UnitEnum::cases

(PHP 8 >= 8.1.0)

UnitEnum::cases — 列挙型の case 一覧を生成する

### 説明

public static function 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)
    }

## 目次

- UnitEnum::cases — 列挙型の case 一覧を生成する

# BackedEnum インターフェイス

(PHP 8 >= 8.1.0)

## はじめに

BackedEnum インターフェイスは、 Backed Enum を定義すると、PHP のエンジンが自動的に適用します。 ユーザー定義のクラスとして実装してはいけません。 列挙型はメソッドのオーバーライドを禁止しています。 デフォルトの実装は PHP のエンジンから提供されるからです。 このインターフェイスは、型チェックのためだけに存在しています。

## インターフェイス概要

interface BackedEnum extends UnitEnum {
/* メソッド */
public static function from(int|string `$value`): static
public static function tryFrom(int|string `$value`): ?static
/* 継承したメソッド */
public static function UnitEnum::cases(): array
}

# BackedEnum::from

(PHP 8 >= 8.1.0)

BackedEnum::from — スカラー型の値を列挙型にマップする

### 説明

public static function 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 を返す

# BackedEnum::tryFrom

(PHP 8 >= 8.1.0)

BackedEnum::tryFrom — スカラー型の値を列挙型にマップするか、`null` を返す

### 説明

public static function 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() - スカラー型の値を列挙型にマップする

## 目次

- BackedEnum::from — スカラー型の値を列挙型にマップする
- BackedEnum::tryFrom — スカラー型の値を列挙型にマップするか、null を返す

# SensitiveParameterValue クラス

(PHP 8 >= 8.2.0)

## はじめに

SensitiveParameterValue クラスを使うと、 秘密の値をうっかり公開してしまうことを防ぐために値をラップすることができます。

SensitiveParameter アトリビュートを持つパラメータに渡される値は、 スタックトレース中では SensitiveParameterValue オブジェクトで自動的にラップされます。

## クラス概要

final class SensitiveParameterValue {
/* プロパティ */
private readonly mixed $value;
/* メソッド */
public function __construct(mixed `$value`)
public function __debugInfo(): array
public function getValue(): mixed
}

## プロパティ

value

  うっかり公開してしまうことを防ぎたい、秘密の値

# SensitiveParameterValue::__construct

(PHP 8 >= 8.2.0)

SensitiveParameterValue::__construct — 新しい SensitiveParameterValue オブジェクトを作成する

### 説明

public function SensitiveParameterValue::__construct(mixed `$value`)

秘密の値を保持した SensitiveParameterValue を作成します。

### パラメータ

`value`

  SensitiveParameterValue オブジェクトの内部に保存すべき、任意の値

# SensitiveParameterValue::__debugInfo

(PHP 8 >= 8.2.0)

SensitiveParameterValue::__debugInfo — 秘密の値をうっかり公開することを防止する

### 説明

public function SensitiveParameterValue::__debugInfo(): array

var_dump() を使った時にうっかり秘密の値を公開しないように、 空の配列を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

空の配列を返します

### 例

例1 SensitiveParameterValue オブジェクトを var_dump() に渡す

    <?php
    $s = new \SensitiveParameterValue('secret');

    var_dump($s);
    ?>

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

    object(SensitiveParameterValue)#1 (0) {
    }

# SensitiveParameterValue::getValue

(PHP 8 >= 8.2.0)

SensitiveParameterValue::getValue — 秘密の値を返す

### 説明

public function SensitiveParameterValue::getValue(): mixed

秘密の値を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

秘密の値を返します。

### 例

例1 SensitiveParameterValue::getValue() の例

    <?php
    $s = new \SensitiveParameterValue('secret');

    echo "The protected value is: ", $s->getValue(), "\n";
    ?>

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

    The protected value is: secret

## 目次

- SensitiveParameterValue::__construct — 新しい SensitiveParameterValue オブジェクトを作成する
- SensitiveParameterValue::__debugInfo — 秘密の値をうっかり公開することを防止する
- SensitiveParameterValue::getValue — 秘密の値を返す

# __PHP_Incomplete_Class クラス

(PHP 4 >=4.0.1, PHP 5, PHP 7, PHP 8)

## はじめに

未定義のクラスや、 unserialize() の `options` 配列の `allowed_classes` のリストに入っていなかったクラスを アンシリアライズしようとした場合に、 unserialize() が生成します。

PHP 7.2.0 より前のバージョンでは、 __PHP_Incomplete_Class に対して is_object() を呼び出すと `false` を返していました。 PHP 7.2.0 以降では `true` を返します。

## クラス概要

#[\AllowDynamicProperties]
final class __PHP_Incomplete_Class {
}

このクラスはデフォルトのプロパティやメソッドを持っていません。 unserialize() がこのクラスを生成した場合、 アンシリアライズされたプロパティやオブジェクトの値について、 アンシリアライズされたクラス名を含む `__PHP_Incomplete_Class_Name` プロパティを持ちます。

## 変更履歴

バージョン | 説明
--- | ---
8.0.0 | このクラスは `final` になりました。

## 例

例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
- DelayedTargetValidation
- Deprecated
- NoDiscard
- Override
- ReturnTypeWillChange
- SensitiveParameter

PHP には、定義済みのアトリビュートがいくつか用意されています。

# Attribute アトリビュート

(PHP 8)

## はじめに

アトリビュートを使うと、 コンピューターが解析できる構造化されたメタデータの情報を、 コードの宣言時に埋め込むことができます。 つまり、クラス、メソッド、関数、パラメータ、プロパティ、クラス定数にアトリビュートを指定することができます。 アトリビュートで定義されたメタデータは、 実行時に リフレクションAPI を使って調べることが出来ます。 よって、アトリビュートは、 コードに直接埋め込むことが出来る、 設定のための言語とみなすことができます。

## クラス概要

#[\Attribute]
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_CONSTANT;
const int TARGET_ALL;
const int IS_REPEATABLE;
/* プロパティ */
public int $flags;
/* メソッド */
public function __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_CONSTANT`

`Attribute::TARGET_ALL`

`Attribute::IS_REPEATABLE`

## プロパティ

flags

## 変更履歴

バージョン | 説明
--- | ---
8.5.0 | `Attribute::TARGET_CONSTANT` が追加されました。

## 参考

アトリビュートの概要

# Attribute::__construct

(PHP 8)

Attribute::__construct — 新しい Attribute のインスタンスを作成する

### 説明

public function Attribute::__construct(int `$flags` = `Attribute::TARGET_ALL`)

新しい Attribute のインスタンスを作成します。

### パラメータ

`flags`

## 目次

- Attribute::__construct — 新しい Attribute のインスタンスを作成する

# AllowDynamicProperties アトリビュート

(PHP 8 >= 8.2.0)

## はじめに

このアトリビュートを使うと、 クラスに 動的なプロパティ を許可することをマークできます。

> 注意: アトリビュート自体は継承されませんが、 `AllowDynamicProperties` アトリビュートの効果は継承されます。 このアトリビュートでマークされたクラスの子クラスは、 明示的にアトリビュートを宣言していなくても、動的なプロパティが許可されます。

## クラス概要

#[\Attribute]
final class AllowDynamicProperties {
/* メソッド */
public function __construct()
}

## 例

動的なプロパティは、PHP 8.2.0 以降は推奨されなくなりました。 よって、このアトリビュートでクラスをマークせずに、 動的なプロパティを使うと、 推奨されない警告が発生します。

例1 存在しないプロパティに対する AllowDynamicProperties

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

例2 継承クラスでの存在しないプロパティに対する AllowDynamicProperties

    <?php
    class DefaultBehaviour { }

    #[\AllowDynamicProperties]
    class ClassAllowsDynamicProperties { }

    class InheritedClassAllowsDynamicProperties extends ClassAllowsDynamicProperties { }

    $o1 = new DefaultBehaviour();
    $o2 = new InheritedClassAllowsDynamicProperties();

    $o1->nonExistingProp = true;
    $o2->nonExistingProp = true;
    ?>

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

    Deprecated: Creation of dynamic property DefaultBehaviour::$nonExistingProp is deprecated in file on line 12

## 参考

アトリビュートの概要

# AllowDynamicProperties::__construct

(PHP 8 >= 8.2.0)

AllowDynamicProperties::__construct — 新しい AllowDynamicProperties のインスタンスを作成する

### 説明

public function AllowDynamicProperties::__construct()

新しい AllowDynamicProperties のインスタンスを作成します。

### パラメータ

この関数にはパラメータはありません。

## 目次

- AllowDynamicProperties::__construct — 新しい AllowDynamicProperties のインスタンスを作成する

# DelayedTargetValidation アトリビュート

(PHP 8 >= 8.5.0)

## はじめに

このアトリビュートは、内部アトリビュートに対する適用対象の検証エラーを、 コンパイル時から、Reflection API を通じてアトリビュートがインスタンス化される時点へと遅延させます。

宣言に適用すると、同じ適用対象における内部アトリビュートの不正な使用は、 コンパイル時のエラーを引き起こしません。代わりに検証は先送りされ、 ReflectionAttribute::newInstance() を通じてアトリビュートがインスタンス化される時点で実行されます。

これは主に前方互換性を意図したものであり、 将来の PHP バージョンで有効な適用対象が追加されうるアトリビュートを使うコードを、 古いバージョンで壊さずに済むようにします。

## クラス概要

#[\Attribute]
final class DelayedTargetValidation {
}

## 例

例1 不正な適用対象の検証を遅延させる

    <?php

    class Base {
        protected function foo(): void {}
    }

    class Child extends Base {

        #[\DelayedTargetValidation]
        #[\Override]
        public const NAME = 'child';

        #[\Override]
        protected function foo(): void {}
    }

Override がクラス定数に対して使えない PHP バージョンであっても、 これはコンパイル時のエラーを発生させません。

例2 検証はリフレクション時に行われる

    <?php

    $reflection = new ReflectionClassConstant(Child::class, 'NAME');

    foreach ($reflection->getAttributes() as $attribute) {
        $attribute->newInstance(); // 不正な場合はスローされる可能性がある
    }

同じ適用対象に適用されたアトリビュート（DelayedTargetValidation 自身を除く）が、 ReflectionAttribute::newInstance() を使ってリフレクション経由でインスタンス化されると、 適用対象の検証が実行され、サポートされていない適用対象でアトリビュートが使われていれば 例外がスローされる可能性があります。

## 注意

このアトリビュートは、内部アトリビュートの適用対象の検証にのみ影響します。

これらのアトリビュートが実行する機能的な検証を抑制するわけではありません。 たとえば Override は、 メソッドが実際には親のメソッドをオーバーライドしていない場合に、引き続きエラーを発生させます。

## 参考

- アトリビュートの概要
- Override

# Deprecated アトリビュート

(PHP 8 >= 8.4.0)

## はじめに

このアトリビュートは、機能を非推奨としてマークします。 マークされた機能を使用すると、`E_USER_DEPRECATED` エラーが発生します。

## クラス概要

#[\Attribute]
final class Deprecated {
/* プロパティ */
public readonly ?string $message;
public readonly ?string $since;
/* メソッド */
public function __construct(?string `$message` = `null`, ?string `$since` = `null`)
}

## プロパティ

message

  非推奨となった理由と可能なら代替機能を説明する追加のメッセージ。 発生する非推奨エラーのメッセージに含まれます。

since

  機能がいつから非推奨になったかを示す追加の文字列。 内容は PHP によって検証されず、バージョン番号、日付、 または適切と考えられる他の値を含むことができます。 発生する非推奨エラーのメッセージに含まれます。

  PHP 自体の機能は、since の値として Major.Minor を利用します。 例えば `'8.4'` です。

## 例

    <?php

    #[\Deprecated(message: "use safe_replacement() instead", since: "1.5")]
    function unsafe_function()
    {
       echo "This is unsafe", PHP_EOL;
    }

    unsafe_function();

    ?>

上の例の PHP 8.4 での出力は、たとえば以下のようになります。:

    Deprecated: Function unsafe_function() is deprecated since 1.5, use safe_replacement() instead in example.php on line 9
    This is unsafe

## 参考

- アトリビュートの概要
- ReflectionFunctionAbstract::isDeprecated()
- ReflectionClassConstant::isDeprecated()
- `E_USER_DEPRECATED`

# Deprecated::__construct

(PHP 8 >= 8.4.0)

Deprecated::__construct — 新しい Deprecated のインスタンスを作成する

### 説明

public function Deprecated::__construct(?string `$message` = `null`, ?string `$since` = `null`)

新しい Deprecated のインスタンスを作成します。

### パラメータ

`message`

  message プロパティの値。

`since`

  since プロパティの値。

## 目次

- Deprecated::__construct — 新しい Deprecated のインスタンスを作成する

# NoDiscard アトリビュート

(PHP 8 >= 8.5.0)

## はじめに

このアトリビュートは、関数やメソッドの戻り値を無視すべきでないことを示すために使います。 戻り値がまったく使われなかった場合、警告が発生します。

これは、戻り値を確認しないことがバグにつながる可能性が高い関数に役立ちます。

このような関数の戻り値を意図的に無視するには、(void) キャストを使って警告を抑制します。

> 注意: アトリビュートは後方互換性を持つように設計されているため、 PHP 8.4 以前をサポートする場合でも `#[\NoDiscard]` を関数やメソッドに追加できます。単に何も起こらないだけです。 PHP 8.5 以降では、戻り値が使われなかった場合に警告が発生します。 PHP 8.5 より前ではサポートされていない `(void)` を使わずに 警告を抑制するには、`$_` のような変数を使うことを検討してください。

## クラス概要

#[\Attribute]
final class NoDiscard {
/* プロパティ */
public readonly ?string $message;
/* メソッド */
public function __construct(?string `$message` = `null`)
}

## プロパティ

message
  戻り値を無視すべきでない理由を説明する、任意のメッセージ。

## 例

例1 基本的な使い方

    <?php

    /**
     * 与えられた全てのアイテムを処理し、各アイテムの処理結果を
     * 配列で返す。`null` は成功を、Exception はエラーを示す。
     * 結果の配列のキーは $items 配列のキーと一致する。
     *
     * @param array<string> $items
     * @return array<null|Exception>
     */
    #[\NoDiscard("as processing might fail for individual items")]
    function bulk_process(array $items): array {
        $results = [];

        foreach ($items as $key => $item) {
            if (\random_int(0, 9999) < 9999) {
                // $item に対して何か有用な処理を行う想定。
                // 99.99% のケースで成功する。
                echo "Processing {$item}", PHP_EOL;
                $error = null;
            } else {
                $error = new \Exception("Failed to process {$item}.");
            }

            $results[$key] = $error;
        }

        return $results;
    }

    bulk_process($items);

    ?>

上の例の PHP 8.5 での出力は、たとえば以下のようになります。:

    Warning: The return value of function bulk_process() should either be used or intentionally ignored by casting it as (void), as processing might fail for individual items

例2 戻り値を意図的に無視する

    <?php

    #[\NoDiscard]
    function some_command(): int {
        return 1;
    }

    // (void) を使って警告を抑制する - PHP 8.5 以降
    (void) some_command();

    // PHP 8.5 より前のバージョンとの互換性のため、一時変数を使う
    $_ = some_command();

    ?>

## 参考

- アトリビュートの概要

# NoDiscard::__construct

(PHP 8 >= 8.5.0)

NoDiscard::__construct — 新しい NoDiscard のインスタンスを作成する

### 説明

public function NoDiscard::__construct(?string `$message` = `null`)

新しい NoDiscard のインスタンスを作成します。

### パラメータ

`message`
  message プロパティの値。

## 目次

- NoDiscard::__construct — 新しい NoDiscard のインスタンスを作成する

# Override アトリビュート

(PHP 8 >= 8.3.0)

## はじめに

このアトリビュートは、 親クラスのメソッドやプロパティをオーバーライドしている意図があるか、 インターフェイスで定義されたプロパティやメソッドを実装していることを示します。

親クラス中に同じ名前のメソッドやプロパティが存在しなかったり、 実装されているインターフェイスがない場合は、 コンパイル時にエラーが発生します。

シグネチャのチェックを回避できてしまうため、 このアトリビュートは __construct() に対しては使えません。

## クラス概要

#[\Attribute]
final class Override {
/* メソッド */
public function __construct()
}

## 変更履歴

バージョン | 説明
--- | ---
8.5.0 | Override は、 プロパティにも適用できるようになりました。

## 例

例1 メソッドと一緒に使う

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

例2 プロパティと一緒に使う

    <?php

    class Base {
        protected string $foo;
    }

    final class Extended extends Base {
        #[\Override]
        protected string $boo;
    }

    ?>

上の例の PHP 8.5 での出力は、たとえば以下のようになります。:

    Fatal error: Extended::$boo has #[\Override] attribute, but no matching parent property exists

## 参考

- アトリビュート

# Override::__construct

(PHP 8 >= 8.3.0)

Override::__construct — 新しいOverrideアトリビュートのインスタンスを作成する

### 説明

public function Override::__construct()

新しい Override のインスタンスを構築します。

### パラメータ

この関数にはパラメータはありません。

## 目次

- Override::__construct — 新しいOverrideアトリビュートのインスタンスを作成する

# ReturnTypeWillChange アトリビュート

(PHP 8 >= 8.1.0)

## はじめに

ほとんどの final でない内部メソッドは、 それをオーバライドする際、 互換性がある戻り値の型を宣言することが必須になっています。 そうしない場合、継承が有効かを検証する際に、 推奨されない警告が発生します。 PHP のバージョン間の互換性を保ちたいがために、 戻り値の型を宣言できない場合、 アトリビュート `#[\ReturnTypeWillChange]` を追加することで警告を抑止できます。

## クラス概要

#[\Attribute]
final class ReturnTypeWillChange {
/* メソッド */
public function __construct()
}

## 参考

アトリビュートの概要

# ReturnTypeWillChange::__construct

(PHP 8 >= 8.1.0)

ReturnTypeWillChange::__construct — 新しい ReturnTypeWillChange のインスタンスを作成する

### 説明

public function ReturnTypeWillChange::__construct()

新しい ReturnTypeWillChange のインスタンスを作成します。

### パラメータ

この関数にはパラメータはありません。

## 目次

- ReturnTypeWillChange::__construct — 新しい ReturnTypeWillChange のインスタンスを作成する

# SensitiveParameter アトリビュート

(PHP 8 >= 8.2.0)

## はじめに

このアトリビュートを使うと、スタックトレース中に現れた場合に、 値を削除すべき秘密の値としてパラメータをマークできます。

## クラス概要

#[\Attribute]
final class SensitiveParameter {
/* メソッド */
public function __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

(PHP 8 >= 8.2.0)

SensitiveParameter::__construct — 新しい SensitiveParameter のインスタンスを作成する

### 説明

public function SensitiveParameter::__construct()

新しい SensitiveParameter のインスタンスを作成します。

### パラメータ

この関数にはパラメータはありません。

## 目次

- SensitiveParameter::__construct — 新しい SensitiveParameter のインスタンスを作成する

# コンテキストオプションとパラメータ

PHP にはさまざまなコンテキストオプションやパラメータがあり、 すべてのファイルシステムラッパーおよびストリームラッパーで使用することができます。 コンテキストの作成は stream_context_create() で行います。オプションの設定は stream_context_set_option() で、そしてパラメータの設定は stream_context_set_params() で行います。

# ソケットコンテキストオプション

ソケットコンテキストオプション — ソケットコンテキストオプション一覧

### 説明

ここでは、ソケット越しに動作するラッパー すなわち `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 コンテキストオプション

HTTP コンテキストオプション — HTTP コンテキストオプションの一覧

### 説明

`http://` および `https://` トランスポート用のコンテキストオプションです。

### オプション

`method` string

  リモートサーバーでサポートされる `GET`、 `POST` あるいはその他の HTTP メソッド。

  デフォルトは `GET` です。

`header` array あるいは string

  リクエストに付加されるヘッダ。ここで指定した値が (`User-agent:`、`Host:`、 および `Authentication:` などの) 他の値を上書きすることもあります。 これは、後に`Location:` によってリダイレクトが行われる場合でも同様です。 よって、`follow_location` が有効になっている場合、 `Host:` ヘッダを設定することはお勧めしません。

  文字列の値は、`Key: value` のペアを `\r\n` で区切ったものにすべきです。 たとえば、 `"Content-Type: application/json\r\nConnection: close"` のようにします。 配列の値は、`Key: value` のペアのリストにすべきです。 たとえば、 `["Content-Type: application/json", "Connection: close"]` のようにします。

`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(
        [
            'var1' => 'some content',
            'var2' => 'doh',
        ]
    );

    $opts = [
        'http' => [
            '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 = [
        'http' => [
            '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 コンテキストオプション

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 コンテキストオプション

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 コンテキストオプション

Phar コンテキストオプション — Phar コンテキストオプション一覧

### 説明

`phar://` ラッパーのコンテキストオプションです。

### オプション

`compress` int

  Phar 圧縮定数 のいずれか。

`metadata` mixed

  Phar メタデータ。Phar::setMetadata() を参照ください。

### 参考

- phar://
- Phar ストリームラッパー

# コンテキストパラメータ

コンテキストパラメータ — コンテキストパラメータの一覧

### 説明

これらの `パラメータ` を `コンテキスト` に設定するには stream_context_set_params() 関数を使用します。

### パラメータ

`notification` callable

  イベントがストリーム上で発生したときにコールされる callable。

  詳細は stream_notification_callback を参照ください。

# Zip コンテキストオプション

Zip コンテキストオプション — Zip コンテキストオプション一覧

### 説明

Zip コンテキストオプションは `zip` ラッパーで使用可能です。

### オプション

`password`

  アーカイブの暗号化に使われたパスワードを指定します。

### 変更履歴

バージョン | 説明
--- | ---
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 コンテキストオプション

Zlib コンテキストオプション — Zlib コンテキストオプション一覧

### 説明

Zlib コンテキストオプションは `zlib` ラッパーで使用可能です。

### オプション

`level`

  圧縮レベル (`0` - `9`) を指定します。

### 変更履歴

バージョン | 説明
--- | ---
7.3.0 | `level` が追加されました。

## 目次

- ソケットコンテキストオプション — ソケットコンテキストオプション一覧
- HTTP コンテキストオプション — HTTP コンテキストオプションの一覧
- FTP コンテキストオプション — FTP コンテキストオプションの一覧
- SSL コンテキストオプション — SSL コンテキストオプションの一覧
- Phar コンテキストオプション — Phar コンテキストオプション一覧
- コンテキストパラメータ — コンテキストパラメータの一覧
- Zip コンテキストオプション — Zip コンテキストオプション一覧
- Zlib コンテキストオプション — Zlib コンテキストオプション一覧

# サポートするプロトコル/ラッパー

PHP には多くの組み込みラッパーが用意されています。さまざまな URL 風のプロトコルによって、 fopen() や copy()、 file_exists() そして filesize() といったファイルシステム関数で使用することができます。 これらのラッパーだけでなく、 stream_wrapper_register() 関数でラッパーを自作することもできます。

> 注意: ラッパーを指定する際の URL 構文としてサポートしているのは `scheme://...` 形式のみです。 `scheme:/` や `scheme:` といった形式には対応していません。

# 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://

# 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://

# 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 コンテキストオプション

# 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'); // 何も表示されません

例6 リクエストボディから、JSON データを読み取るために php://input を使う

この例は、php://input を使って POST, PUT, PATCH リクエスト経由で生の JSON データを読み取る方法を示します。

    <?php
    $input = file_get_contents("php://input");
    $json_array = json_decode(
      json: $input,
      associative: true,
      flags: JSON_THROW_ON_ERROR
    );

    echo "Received JSON data: ";
    print_r($json_array);
    ?>

# 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 コンテキストオプション

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

# 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

# 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 コンテキストオプション

# 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://

rar:// — RAR

### 説明

このラッパーが受け取るのは、RAR アーカイブへの URL エンコードされたパス (絶対パスあるいは相対パス)、そしてオプションでアスタリスク (`*`)、番号記号 (`#`)、 アーカイブ内のエントリ名です。エントリ名を指定する場合は番号記号が必須となります。 エントリ名の先頭のスラッシュは必須ではありません。

このラッパーは、ファイルだけでなくディレクトリも開くことができます。 ディレクトリを開く際にアスタリスクを使うと、 返されるディレクトリエントリ名はエンコードされていない状態となります。 アスタリスクを指定しなかった場合は URL エンコードしたものを返します。 これは、RecursiveDirectoryIterator などの組み込み機能で このラッパーをファイル名の代わりに正しく使えるようにするためです。

番号記号とエントリ名の部分が含まれていない場合は、アーカイブのルートを表示します。 これは通常のディレクトリとは異なり、 返されるストリームには更新時刻などの情報が含まれません。 ルートディレクトリは、アーカイブの個別のエントリとして存在するわけではないからです。 このラッパーを RecursiveDirectoryIterator で使う場合、 ルートにアクセスするには URL に番号記号を含めなければなりません。 そうすれば、子要素の URL も正しく作られます。

> 注意: このラッパーはデフォルトでは有効になっていません
> rar:// ラッパーを使用するには、 » PECL から » rar 拡張モジュールを インストールする必要があります。

rar:// は、PECL rar 3.0.0 以降で使用可能です。

### 利用法

- rar://<url encoded archive name>[*][#[<url encoded entry name>]]

### オプション

ラッパーの概要
属性 | サポートの有無
--- | ---
allow_url_fopen で制約される | No
allow_url_include で制約される | No
読み込み許可 | Yes
書き込み許可 | No
追加許可 | No
同時読み書き許可 | No
stat() のサポート | Yes
unlink() のサポート | No
rename() のサポート | No
mkdir() のサポート | No
rmdir() のサポート | No

コンテキストオプション
名前 | 使用法 | デフォルト
--- | --- | ---
`open_password` | アーカイブのヘッダを暗号化するときに使うパスワード。 WinRAR では、ヘッダの暗号が設定されている場合はすべてのファイルを同じパスワードで暗号化します。 そのため、ヘッダが暗号化されているアーカイブでは `file_password` は無視されます。 |
`file_password` | ファイルを暗号化するときに使うパスワード。 ヘッダが暗号化されている場合はこの設定は無視され、かわりに `open_password` の値を使います。 ふたつのオプションがある理由は、 ヘッダとファイルを別々のパスワードで暗号化する可能性に対応するためです。 アーカイブのヘッダが暗号化されていない場合は `open_password` は無視され、 このオプションを使わなければならないことに注意しましょう。 |
`volume_callback` | 存在しないボリュームのパスを決めるために使うコールバック。詳細は RarArchive::open() を参照ください。 |

### 例

例1 RAR アーカイブの走査

    <?php

    class MyRecDirIt extends RecursiveDirectoryIterator {
        function current() {
            return rawurldecode($this->getSubPathName()) .
                (is_dir(parent::current())?" [DIR]":"");
        }
    }

    $f = "rar://" . rawurlencode(dirname(__FILE__)) .
        DIRECTORY_SEPARATOR . 'dirs_and_extra_headers.rar#';

    $it = new RecursiveTreeIterator(new MyRecDirIt($f));

    foreach ($it as $s) {
        echo $s, "\n";
    }
    ?>

上の例の出力は、 たとえば以下のようになります。

    |-allow_everyone_ni [DIR]
    |-file1.txt
    |-file2_אּ.txt
    |-with_streams.txt
    \-אּ [DIR]
      |-אּ\%2Fempty%2E [DIR]
      | \-אּ\%2Fempty%2E\file7.txt
      |-אּ\empty [DIR]
      |-אּ\file3.txt
      |-אּ\file4_אּ.txt
      \-אּ\אּ_2 [DIR]
        |-אּ\אּ_2\file5.txt
        \-אּ\אּ_2\file6_אּ.txt

例2 暗号化されたファイルのオープン (ヘッダの暗号化)

    <?php
    $stream = fopen("rar://" .
        rawurlencode(dirname(__FILE__)) . DIRECTORY_SEPARATOR .
        'encrypted_headers.rar' . '#encfile1.txt', "r", false,
        stream_context_create(
            array(
                'rar' =>
                    array(
                        'open_password' => 'samplepassword'
                    )
                )
            )
        );
    var_dump(stream_get_contents($stream));
    /* 作成日や最終更新日は WinRAR では選択式になっています。
     * そのため、多くのファイルには含まれていません */
    var_dump(fstat($stream));
    ?>

上の例の出力は、 たとえば以下のようになります。

    string(26) "Encrypted file 1 contents."
    Array
    (
        [0] => 0
        [1] => 0
        [2] => 33206
        [3] => 1
        [4] => 0
        [5] => 0
        [6] => 0
        [7] => 26
        [8] => 0
        [9] => 1259550052
        [10] => 0
        [11] => -1
        [12] => -1
        [dev] => 0
        [ino] => 0
        [mode] => 33206
        [nlink] => 1
        [uid] => 0
        [gid] => 0
        [rdev] => 0
        [size] => 26
        [atime] => 0
        [mtime] => 1259550052
        [ctime] => 0
        [blksize] => -1
        [blocks] => -1
    )

# ogg://

ogg:// — オーディオストリーム

### 説明

ogg:// ラッパー経由で読み込みモードでオープンされた ファイルは、`OGG/Vorbis` コーデックでエンコードされた圧縮音声ファイルとして 扱われます。同様に、ogg:// ラッパー経由で書き込みモード あるいは追記モードでオープンされたファイルは、圧縮音声データとして 書き込まれます。読み込みモードでオープンした `OGG/Vorbis` ファイルに対して stream_get_meta_data() を適用した場合、以下のような さまざまな情報を返します。 `vendor` タグ、`comments`、 多くの `channels`、サンプリングレート `rate` 、 および以下のパラメータで指定されるエンコーディングレート。 `bitrate_lower`、`bitrate_upper`、 `bitrate_nominal`、`bitrate_window`

ogg:// (PECL)

> 注意: このラッパーはデフォルトでは有効になっていません
> ogg:// ラッパーを使用するには、 » PECL から » OGG/Vorbis 拡張モジュールを インストールする必要があります。

### 利用法

- ogg://soundfile.ogg
- ogg:///path/to/soundfile.ogg
- ogg://http://www.example.com/path/to/soundstream.ogg

### オプション

ラッパーの概要
属性 | サポートの有無
--- | ---
allow_url_fopen で制約される | No
読み込み許可 | Yes
書き込み許可 | Yes
追加許可 | Yes
同時読み書き許可 | No
stat() のサポート | No
unlink() のサポート | No
rename() のサポート | No
mkdir() のサポート | No
rmdir() のサポート | No

コンテキストオプション
名前 | 使用法 | デフォルト | モード
--- | --- | --- | ---
`pcm_mode` | 読み込みの際に適用する PCM エンコーディング。以下のうちのひとつ。 `OGGVORBIS_PCM_U8`、`OGGVORBIS_PCM_S8`、 `OGGVORBIS_PCM_U16_BE`、`OGGVORBIS_PCM_S16_BE`、 `OGGVORBIS_PCM_U16_LE`、および `OGGVORBIS_PCM_S16_LE` （8 ビットか 16 ビットか、符号付きか符号なしか、ビッグエンディアンかリトルエンディアンか）。 | OGGVORBIS_PCM_S16_LE | Read
`rate` | 入力データのサンプリングレート。Hz 単位。 | 44100 | Write/Append
`bitrate` | 整数値の場合、エンコードの際の固定ビットレート（16000 から 131072）。 浮動小数点値の場合、使用する可変ビットレート（-1.0 から 1.0）。 | 128000 | Write/Append
`channels` | エンコードする音声チャネル数。一般には 1（モノラル）あるいは 2（ステレオ）。 最大 16 まで。 | 2 | Write/Append
`comments` | エンコード時にトラックヘッダに入れる文字列の配列。 |  | Write/Append

# expect://

expect:// — 対話的プロセスストリーム

### 説明

expect:// ラッパーでオープンしたストリームを使用すると、 プロセスの標準入力・標準出力・標準エラー出力への PTY 経由でのアクセスが 可能となります。

> 注意: このラッパーはデフォルトでは有効となっていません。
> expect:// ラッパーを使用するには、 » PECL にある » Expect 拡張モジュールを インストールする必要があります。

expect:// (PECL)

### 利用法

- expect://command

### オプション

ラッパーの概要
属性 | サポートの有無
--- | ---
allow_url_fopen で制約される | No
読み込み許可 | Yes
書き込み許可 | Yes
追加許可 | Yes
同時読み書き許可 | No
stat() のサポート | No
unlink() のサポート | No
rename() のサポート | No
mkdir() のサポート | No
rmdir() のサポート | No

## 目次

- file:// — ローカルファイルシステムへのアクセス
- http:// — HTTP(s) URL へのアクセス
- ftp:// — FTP(s) URL へのアクセス
- php:// — さまざまな入出力ストリームへのアクセス
- zlib:// — 圧縮ストリーム
- data:// — データ (RFC 2397)
- glob:// — パターンにマッチするパス名の検索
- phar:// — PHP アーカイブ
- ssh2:// — Secure Shell 2
- rar:// — RAR
- ogg:// — オーディオストリーム
- expect:// — 対話的プロセスストリーム

- 基本的な構文
  - PHP タグ
  - HTML からの脱出
  - 命令の分離
  - コメント
- 型
  - はじめに
  - 型システム
  - NULL
  - 論理型 (boolean)
  - 整数
  - 浮動小数点数
  - 文字列
  - 数値形式の文字列
  - 配列
  - オブジェクト
  - 列挙型 / Enum
  - リソース
  - コールバック / Callable
  - Mixed
  - Void
  - Never
  - クラス内での関係を示す相対型
  - シングルトン型
  - 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 — クエリストリング変数
  - $_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
  - RequestParseBodyException
- 定義済みのインターフェイスとクラス
  - Traversable — Traversable インターフェイス
  - Iterator — Iterator インターフェイス
  - IteratorAggregate — IteratorAggregate インターフェイス
  - InternalIterator — InternalIterator クラス
  - Throwable
  - Countable — Countable インターフェイス
  - 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 アトリビュート
  - DelayedTargetValidation — DelayedTargetValidation アトリビュート
  - Deprecated — Deprecated アトリビュート
  - NoDiscard — NoDiscard アトリビュート
  - 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 は強力な言語そしてインタプリタであり、モジュールとして 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 は、ユーザーホームディレクトリ以下のファイルを開かず、 `user_dir` 以下の ~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/passwd のようなシステム ファイルを読み込み可能としたり、イーサネット接続を修正したり、巨大 なプリンタジョブを出力したりすることができます。これから明らかにわ かることですが、読み書きするファイルを適切に設定する必要があります。

各自のホームディレクトリにあるファイルを削除する次のスクリプトを見 てみましょう。これは、ファイル管理用に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";
    }
    j
    $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/ または /dev/)、設定ファイル(/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` (これらは両方、PHP 5.4.0 で削除されています) のような機能が、ユーザーの入力から自動的に変数を生成したり、 データを不完全な形でエスケープしたりすることで、セキュリティリスクを拡大することに貢献していました。 PHP ではそうしたリスクはなくなったものの、 入力処理の管理を誤れば、同様のリスクは依然として存在します。

error_reporting(E_ALL) を有効にし、未初期化の変数を検知し、入力を検証してください。 型安全を強制し、意図しない型変換を防止し、セキュリティ全体を改善するために、 strict モード (PHP 7 で導入された declare(strict_types=1)) を利用してください。

# 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 は、他の大規模なシステムと同様に、セキュリティを確保しつつ 改良されています。新バージョンにはしばしば大規模あるいは小規模な 変更が含まれています。その内容は、セキュリティの機能追加であったり セキュリティ上の問題・設定の不備・その他システム全体のセキュリティや 安定性にかかわる問題の修正であったりします。

他のシステムレベルのスクリプト言語やプログラムと同様に、最善の アプローチは、頻繁に更新し、最新のバージョンとその変更を 注視し続けることです。

- はじめに
- 一般的な考慮事項
- CGI バイナリとしてインストール
  - 受ける可能性がある攻撃
  - ケース 1: 配布制限がないファイルのみを配布
  - ケース 2: cgi.force_redirect を使用
  - ケース 3: doc_root または user_dir を設定
  - ケース 4: Webツリーの外にPHPパーサーを置く
- Apache モジュールとしてインストール
- セッションのセキュリティ
- ファイルシステムのセキュリティ
  - Null バイト関連の問題
- データベースのセキュリティ
  - データベースのデザイン
  - データベースへの接続
  - ストレージの暗号化
  - SQLインジェクション
- エラーのレポート
- ユーザーが投稿したデータ
- PHPの隠蔽
- 最新版を維持する

# 機能

# PHP による HTTP 認証

header() 関数を使うと、 `"Authentication Required"` メッセージをクライアントブラウザに送ることができます。 これにより、クライアントブラウザではユーザー名とパスワードの入力要求 ウインドウがポップアップ表示されます。一度、ユーザーがユーザー名と パスワードを入力すると、PHP スクリプトを含むその URL は、次回以降、 定義済みの変数 PHP_AUTH_USER と、 PHP_AUTH_PW と、 AUTH_TYPE にそれぞれユーザー名、 パスワード、認証型が代入された状態で呼ばれます。 定義済みの変数は、配列 $_SERVER でアクセス可能です。 "Basic" 認証 のみ がサポートされています。詳細は、 header()を参照ください。

ページ上でクライアント認証を強制するスクリプトの例を以下に示します。

例1 Basic HTTP 認証の例

    <?php
    if (!isset($_SERVER['PHP_AUTH_USER'])) {
        header('HTTP/1.1 401 Unauthorized');
        header('WWW-Authenticate: Basic realm="My Realm"');
        echo "ユーザーがキャンセルボタンを押した時に送信されるテキスト\n";
        exit;
    } else {
        echo "<p>こんにちは、{$_SERVER['PHP_AUTH_USER']} さん。</p>";
        echo "<p>あなたは、{$_SERVER['PHP_AUTH_PW']} をパスワードとして入力しました。</p>";
    }
    ?>

> 注意: 互換性

> HTTPヘッダ行をコーディングする際には注意を要します。全てのクライアントへの 互換性を最大限に保証するために、キーワード "Basic" には、 大文字の"B"を使用して書くべきです。realm文字列は(一重引用符ではなく) 二重引用符で括る必要があります。また、HTTP/1.1 401 ヘッダ行のコード 401 の前には、 1つだけ空白を置く必要があります。 認証パラメータは、 カンマ区切りで指定しなければなりません。

単に PHP_AUTH_USERおよびPHP_AUTH_PW を出力するのではなく、ユーザー名とパスワードの有効性をチェックしたいと 思うかもしれません。 その場合、クエリーをデータベースに送るか、ある dbm ファイル中の ユーザーを調べるといったことをすることになるでしょう。

> 注意: Apache の設定

> PHP は、外部認証が動作しているかどうかの判定を `AuthType` ディレクティブの有無で行います。

しかし、上記の機能も、認証を要求されないURLを管理する人が同じサーバー にある認証を要するURLからパスワードを盗むことを防ぐわけではありませ ん。

> 注意: ブラウザの挙動
> HTTP Basic 認証は非常に基本的なもので、ログアウトをサポートするようには 設計されていません。HTTP はステートレスなプロトコルであるため、 ほとんどのブラウザは `2xx` ステータスコードを受け取ると すぐに認証情報をキャッシュし、ブラウザを閉じるまですべてのリクエストで その認証情報を送信し続けます。サーバーが認証情報の再入力を求める プロンプトを要求するための標準的な方法は定義されていません。 長年にわたり、この問題に対するさまざまな回避策がインターネット上で 広まってきましたが、それらはすべて、異なるブラウザが未定義のエッジケース （あるいは HTTP 標準の違反さえも）をどのように処理するかに依存しています。 このような回避策は避け、Basic 認証を重要な用途に使用しないことが最善です。

> 注意: IIS の設定
> IIS サーバーと CGI 版の PHP の組み合わせで HTTP 認証を使うには、 php.ini ディレクティブ cgi.rfc2616_headers を `0` (デフォルト値) に設定し、IIS の設定の "`ディレクトリセキュリティ`" を編集する必要があります。 "`編集`" ボタンを押して "`匿名アクセス`" のみをオンにしてください。 その他のフィールドはオフのままにしてください。

# クッキー(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_*` 定数のひとつです。

## 陥りやすい落とし穴

`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);
    ?>

## 参考

- ファイルシステムのセキュリティ

# リモートファイルの使用

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 は(前もってオープンされたままになっている) 同じ持続的接続が既にオープンされていないかどうかを確認します。 そして、存在する場合には、それを再利用します。存在しない場合には、 そのリンクを作成します。'同じ'接続とは、同じホスト、同じユーザー名、 同じパスワード(利用可能な場合)でオープンされた接続のことを意味します。

特定の接続を要求する方法はありませんし、 既存の接続と新しい接続のどちらを取得できるかを保証する方法もありません。 (すべての接続が使用中の場合や、 リクエストが別の接続プールを持つ、 別のワーカーによって処理される場合があります)

したがって、PHP の持続的接続は、たとえば以下の目的には使えません:

- 特定のデータベースセッションを特定のWebユーザーに割り当てる
- 複数のリクエストにまたがる巨大なトランザクションを生成する
- あるリクエストでクエリを発行し、クエリの結果を別のリクエストで収集する

持続的接続は、 持続的でない接続にできない機能は 全く 提供しません。

### Webリクエスト

Webサーバーを PHP と統合し、Webページを生成させる方法はふたつあります:

最初は、CGI "ラッパー"としてPHPを使用する方法です。このように実行した場合、 PHP インタプリタのインスタンスは、Webサーバーに(PHPページに関する) ページがリクエストされる度に生成され、破棄されます。 リクエスト毎に破棄されるために、(SQLデータベースサーバーへのリンクのような) 必要な全てのリソースは破棄される際にクローズされます。この場合、 持続的接続を使用することから得るものは何もありません。 持続的接続は持続しないのです。

2番目は、最も一般的ですが、PHP を PHP-FPM か、 マルチプロセスWebサーバー(現在はApacheのみ)のモジュールとして実行する方法です。 マルチプロセスサーバーは、通常、 実際にWebページの提供を行う複数のプロセス(子)を管理するプロセス(親)を有しています。 リクエストがクライアントから来ると、 親プロセスは、 他のクライアントにすでに送信を行っていないクライアントの一つに渡します。 このため、 同じクライアントが2番目のリクエストをサーバーに送信した際に最初のではなく他の子プロセスにより送信が行われる可能性があります。 持続的接続がオープンされると、 同じ子プロセスが処理する後続のページは、 SQL サーバーへの確立済みの接続を再利用することができます。

> 注意:

> Webリクエスト で使用されているメソッドを確認するには、 phpinfo() の出力における "Server API" の値、 または Webリクエスト から実行した `PHP_SAPI` の値を確認してください。

> サーバーAPI が "Apache 2 Handler" や "FPM/FastCGI" の場合、 持続的接続は同じワーカーで処理されるリクエスト間で使われます。 これら以外の値の場合、 持続的接続はそれぞれのリクエストを処理したあとは持続しません。

### コマンドラインのプロセス

コマンドラインから実行する PHP は、 スクリプトごとに新しいプロセスを使います。 持続的接続は、コマンドラインから実行するスクリプト間では共有されません。 よって、cron やコマンドからのような一時的なスクリプトから、 持続的接続を使ってもなんの役にも立ちません。 とはいっても、役に立つ場面はあるかもしれません。 たとえば、多くのリクエストやタスクを処理し、 それぞれが独自のデータベース接続を必要とする可能性のある、 長時間実行のアプリケーションサーバーの場合が挙げられます。

### 持続的接続をなぜ使うのか？

持続的接続は、SQLサーバーへ接続するオーバーヘッドが大きい場合に有効です。 このオーバーヘッドが大きいかどうかは、データベースの種類、 Webサーバーと同じマシン上にあるかどうか、 そのマシンの負荷など、様々な要因に依存します。 接続のオーバーヘッドが大きい場合、 持続的接続は著しく効果があります: 子プロセスは、SQLサーバーへの接続が必要なページを処理するたびに接続するのではなく、 動作中に一度だけ接続を行います。 このことは、 持続的接続をオープンした子プロセスがそれぞれ、 サーバーへの接続を維持するということになります。 例えば、 20の異なった子プロセスがそれぞれSQLサーバーへの持続的接続を行うスクリプトを実行した場合、 そのサーバーへの個別の接続が、各子プロセスから1つずつ、合計20本行われます。

### ありうる欠点: 接続数の上限

しかし、データベースへの接続数を制限して使用している場合に、 持続的な子プロセスの接続数がその数を超える場合は、 持続的接続には気をつけたほうが良い欠点がいくつかあります。 もしデータベースの同時接続数の制限が16だとして、 サーバーに多くのアクセスがあったため、 17個の子プロセスが接続しようとするとそのうちの一つは接続に失敗します。 もしスクリプトに接続をシャットダウンしないようなバグ(例えば無限ループ)があると、 16程度の同時接続しか許容しないデータベースはすぐにダメになってしまいます。

持続的接続は通常、特定の時点で開く接続数を増加させます。 これはアイドル状態のワーカーが、 以前処理したリクエスト用の接続を保持し続けるためです。 リクエストの急増に対応するために多数のワーカーが起動された場合、 それらのワーカーが開いた接続は、 ワーカーが終了するかデータベースサーバーが接続を閉じるまで残ります。

データベースサーバーが許可する最大接続数が、 Webリクエストワーカーの最大数(それに cronジョブや、 管理接続などのその他の使用分を加えた数)よりも大きいことを確認してください。

放棄された接続や、アイドル状態の接続(タイムアウト)の処理方法について、 データベースのドキュメントで確認してください。 タイムアウトを長く設定すると、 同時に開かれる持続的接続の数が大幅に増加する可能性があります。

### ありうる欠点: 接続の状態管理

一部のデータベース拡張モジュールは、 接続が再利用される際にクリーンアップを自動的に実行します。 このクリーンアップのタスクを、 アプリケーション開発者の裁量に委ねる拡張モジュールもあります。 選択したデータベース拡張モジュールとアプリケーション設計によっては、 スクリプト終了前に手動でのクリーンアップが必要になる場合があります。 接続を予期しない状態に陥らせる可能性のある変更には以下が含まれます：

- データベースの選択 / デフォルトのデータベース
- テーブルロック
- 未コミットのトランザクション
- 一時テーブル
- プロファイリングのような、特定の設定や機能を有効にした接続

クリーンアップが行われていない、 または閉じられていないテーブルロックやトランザクションは、 他のクエリが無限にブロックされる原因となるほか、 その後の接続の再利用によって予期しない変更が生じる可能性があります。

誤ったデータベースが選択されている場合、 その後の接続の再利用ではクエリが期待通りに実行できなくなります (スキーマが十分に類似している場合、 誤ったデータベース上でクエリが実行される可能性があります)。

一時テーブルがクリーンアップされない場合、 後続のリクエストでは同じテーブルを再作成できません。

クリーンアップは、クラスのデストラクタまたは register_shutdown_function()を使用して実装できます。 また、クリーンアップの機能を組み込んだ、 専用の接続プールプロキシの使用も検討するとよいでしょう。

### おわりに

既に述べた持続的接続の振る舞いと、あり得る欠点を考慮すると、 持続的接続を使う場合は、必ず慎重に検討を行うべきです。 持続的接続を使う場合は、 アプリケーションを追加で変更し、 データベースサーバーとWebサーバーおよび/またはPHP-FPMを慎重に設定すべきです。

サーバーへ接続するオーバーヘッドの原因を調査・修正する別の代替案 (例：データベースサーバーへのDNS逆引きの無効化）や、 専用の接続プールプロキシを検討してください。

高トラフィックのWeb APIについては、代替のランタイムや、 長時間実行可能なアプリケーションサーバーの使用を検討してください。

### 参考

- ibase_pconnect()
- oci_pconnect()
- odbc_pconnect()
- pfsockopen()
- pg_connect()
- MySQLi and Persistent Connections
- PDO Connection Management

# 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'] を使うこともできます。 警告 $argv や $_SERVER['argv'] が存在することは、PHPスクリプトがコマンドラインから実行されていることを示す信頼できる根拠にはなりません。 なぜなら、register_argc_argv が有効になっている場合に、他のコンテキストで設定されている可能性があるからです。 コマンドラインから実行されていることを確認するには、代わりに php_sapi_name() の返り値をチェックすべきです。
      <?php

      if (php_sapi_name() === 'cli') {
          echo "This is being run from the command line!\n";
      }
  警告 この機能は PHP 8.5.0 で 非推奨 になります。この機能に頼らないことを強く推奨します。
  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.

      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) を見つけることはありません。そうするためには、 コード全体を実行する必要があるからです。 注意: PHP 8.3.0 より前のバージョンでは、 構文チェックできるファイルの数は一つだけでした。 注意: このオプションは、オプション -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 オプションと同時に 使用することはできません。
| --ini | 設定ファイルの名前、設定ファイルを検索するディレクトリを表示します。 オプションで `--ini=diff` を渡すと、 ロードされた設定ファイルとデフォルトの設定との差分を表示します。 例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)
注意: `--ini=diff` オプションは PHP 8.5.0 より前では使用できません。
--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 ファイルです。 PHP 8.4.0 以降では、環境変数 PHP_HISTFILE を使って 履歴ファイルのパスを設定できます。

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)から与えなければいけません。 スクリプトを入力後、 ``CTRL` +`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 ではサポートされていません。

> 注意: PHP のコマンドラインの使い方やオプションについては、 php --help または man php を実行してください。 すべてのオプションがウェブサーバーの実行時に適用されるわけではありません。

警告

この機能は 実験的なもの であり、 本番環境で使うことを意図した機能では ありません。 ビルトインウェブサーバーは本番環境で使うものではありません。

例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";
        }
    }
    ?>

このとても学術的な例では、 プロパティがオブジェクト自身を指すように設定されたオブジェクトを作成します。 スクリプト内の $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 静的プローブとともに bpftrace を使用

## 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 拡張モジュールも、 共用拡張モジュールとして別々にビルドするべきです。

静的プローブを有効にするには、USE_ZEND_DTRACE=1環境変数を対象となる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 DTrace 静的プローブとともに bpftrace を使用

LinuxディストリビューションにおいてカーネルがeBPFをサポートする場合、bpftraceユーティリティはPHPのDTraceプローブ（USDT）に対してSystemTapを必要とせず直接アタッチすることができます。

### bpftraceのインストール

bpftraceをパッケージマネージャを利用してインストールします。例えばOracle Linux、RHELまたはFedoraの場合は

    # dnf install bpftrace

Debian、Ubuntuの場合は以下のコマンドでインストールします。

    # apt install bpftrace

下記の例ではターゲットとなるPHPバイナリのインストール先は /usr/bin/phpであると仮定しています。

同じUSDTプローブは同一のソースツリーからビルドされた他のSAPIでも利用可能であり、プローブのターゲットはApache module (libphp.so)またはFastCGI Process Manager バイナリ (php-fpm)となる場合もあります。必要に応じて適切なパスに置き換えや、 `-p`によるPID指定を行いアタッチしてください。

ターゲットバイナリでDTraceが有効になっていること、環境変数が適切に設定されていることを確認してください。 詳細はDTrace 静的プローブのために PHP を構成で参照できます。

PHPの静的プローブをリストするには以下のbpftraceコマンドを使用します。

    # bpftrace -l 'usdt:/usr/bin/php:php:*'

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

    usdt:/usr/bin/php:php:compile__file__entry
    usdt:/usr/bin/php:php:compile__file__return
    usdt:/usr/bin/php:php:error
    usdt:/usr/bin/php:php:exception__caught
    usdt:/usr/bin/php:php:exception__thrown
    usdt:/usr/bin/php:php:execute__entry
    usdt:/usr/bin/php:php:execute__return
    usdt:/usr/bin/php:php:function__entry
    usdt:/usr/bin/php:php:function__return
    usdt:/usr/bin/php:php:request__shutdown
    usdt:/usr/bin/php:php:request__startup

例1 bpftraceを使用してすべてのPHP静的プローブをトレースするall_probes.bt

    #!/usr/bin/env bpftrace

    usdt:/usr/bin/php:php:compile__file__entry
    {
        printf("Probe compile__file__entry\n");
        printf("  compile_file %s\n", str(arg0));
        printf("  compile_file_translated %s\n", str(arg1));
    }
    usdt:/usr/bin/php:php:compile__file__return
    {
        printf("Probe compile__file__return\n");
        printf("  compile_file %s\n", str(arg0));
        printf("  compile_file_translated %s\n", str(arg1));
    }
    usdt:/usr/bin/php:php:error
    {
        printf("Probe error\n");
        printf("  errormsg %s\n", str(arg0));
        printf("  request_file %s\n", str(arg1));
        printf("  lineno %d\n", (int32)arg2);
    }
    usdt:/usr/bin/php:php:exception__caught
    {
        printf("Probe exception__caught\n");
        printf("  classname %s\n", str(arg0));
    }
    usdt:/usr/bin/php:php:exception__thrown
    {
        printf("Probe exception__thrown\n");
        printf("  classname %s\n", str(arg0));
    }
    usdt:/usr/bin/php:php:execute__entry
    {
        printf("Probe execute__entry\n");
        printf("  request_file %s\n", str(arg0));
        printf("  lineno %d\n", (int32)arg1);
    }
    usdt:/usr/bin/php:php:execute__return
    {
        printf("Probe execute__return\n");
        printf("  request_file %s\n", str(arg0));
        printf("  lineno %d\n", (int32)arg1);
    }
    usdt:/usr/bin/php:php:function__entry
    {
        printf("Probe function__entry\n");
        printf("  function_name %s\n", str(arg0));
        printf("  request_file %s\n", str(arg1));
        printf("  lineno %d\n", (int32)arg2);
        printf("  classname %s\n", str(arg3));
        printf("  scope %s\n", str(arg4));
    }
    usdt:/usr/bin/php:php:function__return
    {
        printf("Probe function__return\n");
        printf("  function_name %s\n", str(arg0));
        printf("  request_file %s\n", str(arg1));
        printf("  lineno %d\n", (int32)arg2);
        printf("  classname %s\n", str(arg3));
        printf("  scope %s\n", str(arg4));
    }
    usdt:/usr/bin/php:php:request__shutdown
    {
        printf("Probe request__shutdown\n");
        printf("  file %s\n", str(arg0));
        printf("  request_uri %s\n", str(arg1));
        printf("  request_method %s\n", str(arg2));
    }
    usdt:/usr/bin/php:php:request__startup
    {
        printf("Probe request__startup\n");
        printf("  file %s\n", str(arg0));
        printf("  request_uri %s\n", str(arg1));
        printf("  request_method %s\n", str(arg2));
    }

上記のスクリプトはPHPのスクリプトの実行中のすべてのコアPHP静的プローブポイントをトレースします。bpftraceの実行にはroot権限が必要です。

    # USE_ZEND_DTRACE=1 bpftrace -c '/usr/bin/php test.php' all_probes.bt

すでに実行中のPHPプロセス (例えば php-fpm ワーカー、または libphp.soをロードするapacheプロセス)はPIDを指定してアタッチできます。

    # bpftrace -p $PID all_probes.bt

スクリプト中の`usdt:` ターゲットパスは実行しているプロセスのバイナリにマッチする必要があります。 `usdt:/usr/bin/php`部分を php-fpm バイナリまたは libphp.so などのパスに必要に応じて修正してください。

- PHP による HTTP 認証
- クッキー(Cookies)
- セッション
- ファイルアップロードの処理
  - POST メソッドによるアップロード
  - エラーメッセージの説明
  - 陥りやすい落とし穴
  - 複数ファイルのアップロード
  - PUT メソッドのサポート
  - 参考
- リモートファイルの使用
- 接続処理
- 持続的データベース接続
- コマンドラインの使用法 — PHP をコマンドラインから使用する
  - 他の SAPI との違い
  - オプション — コマンドラインオプション
  - PHP ファイルの実行
  - I/O ストリーム — 入出力ストリーム
  - 対話シェル
  - ビルトインウェブサーバー
  - INI 設定
- ガベージコレクション
  - リファレンスカウントの原理
  - 循環の収集
  - パフォーマンスの考慮点
- DTrace 動的トレーシング
  - PHP および DTrace への入門
  - PHP および DTrace の使用
  - PHP DTrace 静的プローブとともに SystemTap を使用
  - PHP DTrace 静的プローブとともに bpftrace を使用

# 関数リファレンス

ヒント

参考 拡張モジュールの一覧/分類.

# PHP の振る舞いの変更

# APC User Cache

# はじめに

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 以降でサポートされています。

# インストール/設定

## 目次

- インストール手順
- 実行時設定

## インストール手順

この 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 | 512 * apc.shm_size | `INI_SYSTEM` | APCu 5.1.25 より前のバージョンでは、この値のデフォルト値は 4096 でした。
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
  削除されたり、無効になったキャッシュエントリがガベージコレクションのリストに残っても良い秒数。 エントリは、リファレンスカウントがゼロになった時、またはこの設定の秒数を越えた場合に、削除候補になります。 `0` を設定すると、時間ベースの削除機能は無効になり、リファレンスカウントがゼロになったときにのみ削除されます。
`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

(PECL apcu >= 4.0.0)

apcu_add — 新規の変数をデータ領域にキャッシュする

### 説明

function apcu_add(string `$key`, mixed `$var`, int `$ttl` = 0): bool
function 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_cache_info

(PECL apcu >= 4.0.0)

apcu_cache_info — APCu のデータから、キャッシュされた情報を取得する

### 説明

function apcu_cache_info(bool `$limited` = `false`): array|false

APCu のデータから、キャッシュされた情報およびメタデータを取得します。

### パラメータ

`limited`
  `limited` が `true` の場合は、 戻り値にキャッシュエントリの個々の一覧が含まれません。 これは、統計情報の収集時に呼び出しを最適化したい場合などに有用です。

### 戻り値

キャッシュされたデータ（およびメタデータ）の配列を返します。 失敗した場合に `false` を返します

> 注意: もし APCu キャッシュのデータを取得できなかった場合、 apcu_cache_info() は警告を発生します。これが起こるのは、 一般的には APCu が有効になっていない場合などです。

### 変更履歴

バージョン | 説明
--- | ---
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_cas

(PECL apcu >= 4.0.0)

apcu_cas — 古い値を新しい値に更新する

### 説明

function 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_clear_cache

(PECL apcu >= 4.0.0)

apcu_clear_cache — APCu キャッシュをクリアする

### 説明

function apcu_clear_cache(): bool

キャッシュをクリアします。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

常に `true` を返します。

### 参考

- apcu_cache_info() - APCu のデータから、キャッシュされた情報を取得する

# apcu_dec

(PECL apcu >= 4.0.0)

apcu_dec — 保存した数値を減らす

### 説明

function 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_delete

(PECL apcu >= 4.0.0)

apcu_delete — 格納されている変数をキャッシュから取り除く

### 説明

function 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_enabled

(PECL apcu >= 4.0.3)

apcu_enabled — 現在の環境で apcu が使えるかを確認する

### 説明

function apcu_enabled(): bool

現在の環境で apcu が使えるかどうかを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

現在の環境で apcu が使えるなら `true` を、そうでなければ `false` を返します。

# apcu_entry

(PECL apcu >= 5.1.0)

apcu_entry — アトミックに値を取得するか、キャッシュエントリを生成する

### 説明

function apcu_entry(string `$key`, callable `$callback`, int `$ttl` = 0): mixed

キャッシュに `key` が存在するかをアトミックに検索します。 存在しなければ `callback` が呼び出され、 `key` が唯一の引数として渡されます。 `callback` ではオプションで指定する `ttl` の間だけ値をキャッシュし、 キャッシュした値が返されます。

> 注意: apcu_entry() 関数に制御が移ると、 キャッシュのロックを排他的に取得します。 このロックは apcu_entry() の実行が終わったときに開放されます: この結果、`callback` はクリティカルセクションに入るため、 ふたつのプロセスが同時に同じコードパスを実行することができなくなります。 さらに、他のAPCuのあらゆる関数も同時に並列に実行できなくなります。 なぜなら、同じロックを共有しているからです。

警告

`callback` から安全に呼び出せるAPCuの関数は apcu_entry() だけです。

### パラメータ

`key`
  キャッシュエントリのキー。
`callback`
  `key` を唯一の引数として取り、 キャッシュする値を返す関数
`ttl`
  有効期間。`callback` の戻り値は、キャッシュに `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_exists

(PECL apcu >= 4.0.0)

apcu_exists — エントリが存在するかどうかを調べる

### 説明

function 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_fetch

(PECL apcu >= 4.0.0)

apcu_fetch — 格納されている変数をキャッシュから取得する

### 説明

function 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_inc

(PECL apcu >= 4.0.0)

apcu_inc — 保存した数値を増やす

### 説明

function 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_key_info

(PECL apcu >= 4.0.2)

apcu_key_info — キャッシュのキーに関する詳細な情報を取得する

### 説明

function 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_sma_info

(PECL apcu >= 4.0.0)

apcu_sma_info — APCu の共有メモリ割り当てに関する情報を取得する

### 説明

function 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_store

(PECL apcu >= 4.0.0)

apcu_store — 変数をデータ領域にキャッシュする

### 説明

function apcu_store(string `$key`, mixed `$var`, int `$ttl` = 0): bool
function 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() - 格納されている変数をキャッシュから取り除く

## 目次

- 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 クラス

(PECL apcu >= 5.0.0)

## はじめに

APCUIterator クラスを使うと、巨大な APCu キャッシュの反復処理を容易に行えます。 巨大なキャッシュを順を追って処理し、 ロックインスタンス単位で決まった数のエントリを取得することができます。 そのため、キャッシュ全体を抱え込んで 100 件 (デフォルト) のエントリを取り込むのではなく、 キャッシュのロックを解放して他の操作ができる状態にすることが可能です。 また、正規表現によるマッチングは C 言語レベルで行われるのでより効率的です。

## クラス概要

class APCUIterator implements Iterator {
/* メソッド */
public function __construct(
array|string|null `$search` = `null`,
int `$format` = APC_ITER_ALL,
int `$chunk_size` = 100,
int `$list` = APC_LIST_ACTIVE
)
public function current(): mixed
public function getTotalCount(): int
public function getTotalHits(): int
public function getTotalSize(): int
public function key(): string
public function next(): bool
public function rewind(): void
public function valid(): bool
}

# APCUIterator::__construct

(PECL apcu >= 5.0.0)

APCUIterator::__construct — APCUIterator イテレータオブジェクトを作成する

### 説明

public function 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::current

(PECL apcu >= 5.0.0)

APCUIterator::current — 現在の項目を取得する

### 説明

public function APCUIterator::current(): mixed

APCUIterator から現在の項目を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に現在の項目を返します。 もう項目が存在しない場合や取得に失敗した場合は `false` を返します。

### 参考

- APCUIterator::next() - ポインタを次の項目に移動させる
- Iterator::current() - 現在の要素を返す

# APCUIterator::getTotalCount

(PECL apcu >= 5.0.0)

APCUIterator::getTotalCount — 総数を取得する

### 説明

public function APCUIterator::getTotalCount(): int

総数を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

総数を返します。

### 参考

- APCUIterator::getTotalHits() - キャッシュヒットの総数を取得する
- APCUIterator::getTotalSize() - キャッシュのサイズの合計を取得する
- apcu_cache_info() - APCu のデータから、キャッシュされた情報を取得する

# APCUIterator::getTotalHits

(PECL apcu >= 5.0.0)

APCUIterator::getTotalHits — キャッシュヒットの総数を取得する

### 説明

public function APCUIterator::getTotalHits(): int

キャッシュヒットの総数を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合にヒット数、失敗した場合に `false` を返します。

### 参考

- APCUIterator::getTotalCount() - 総数を取得する
- APCUIterator::getTotalSize() - キャッシュのサイズの合計を取得する
- apcu_cache_info() - APCu のデータから、キャッシュされた情報を取得する

# APCUIterator::getTotalSize

(PECL apcu >= 5.0.0)

APCUIterator::getTotalSize — キャッシュのサイズの合計を取得する

### 説明

public function APCUIterator::getTotalSize(): int

キャッシュのサイズの合計を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

キャッシュのサイズの合計を返します。

### 参考

- APCUIterator::getTotalCount() - 総数を取得する
- APCUIterator::getTotalHits() - キャッシュヒットの総数を取得する
- apcu_cache_info() - APCu のデータから、キャッシュされた情報を取得する

# APCUIterator::key

(PECL apcu >= 5.0.0)

APCUIterator::key — イテレータのキーを取得する

### 説明

public function APCUIterator::key(): string

現在のイテレータのキーを取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合にキー、失敗した場合に `false` を返します。

### 参考

- APCUIterator::current() - 現在の項目を取得する
- Iterator::key() - 現在の要素のキーを返す

# APCUIterator::next

(PECL apcu >= 5.0.0)

APCUIterator::next — ポインタを次の項目に移動させる

### 説明

public function APCUIterator::next(): bool

イテレータのポインタを次の要素に移動させます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- APCUIterator::current() - 現在の項目を取得する
- APCUIterator::rewind() - イテレータを巻き戻す
- Iterator::next() - 次の要素に進む

# APCUIterator::rewind

(PECL apcu >= 5.0.0)

APCUIterator::rewind — イテレータを巻き戻す

### 説明

public function APCUIterator::rewind(): void

イテレータを最初の要素に巻き戻します

### パラメータ

この関数にはパラメータはありません。

### 戻り値

値を返しません。

### 参考

- APCUIterator::next() - ポインタを次の項目に移動させる
- Iterator::next() - 次の要素に進む

# APCUIterator::valid

(PECL apcu >= 5.0.0)

APCUIterator::valid — 現在位置が有効かどうかを調べる

### 説明

public function APCUIterator::valid(): bool

イテレータの現在位置が有効かどうかを調べます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

イテレータの現在位置が有効な場合に `true`、それ以外の場合に `false` を返します。

### 参考

- APCUIterator::current() - 現在の項目を取得する
- Iterator::valid() - 現在位置が有効かどうかを調べる

## 目次

- APCUIterator::__construct — APCUIterator イテレータオブジェクトを作成する
- APCUIterator::current — 現在の項目を取得する
- APCUIterator::getTotalCount — 総数を取得する
- APCUIterator::getTotalHits — キャッシュヒットの総数を取得する
- APCUIterator::getTotalSize — キャッシュのサイズの合計を取得する
- APCUIterator::key — イテレータのキーを取得する
- APCUIterator::next — ポインタを次の項目に移動させる
- APCUIterator::rewind — イテレータを巻き戻す
- APCUIterator::valid — 現在位置が有効かどうかを調べる

- インストール/設定
  - インストール手順
  - 実行時設定
- 定義済み定数
- 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 — 現在位置が有効かどうかを調べる

# Componere

# はじめに

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 function Componere\Definition::__construct(string `$name`)
public function Componere\Definition::__construct(string `$name`, string `$parent`)
public function Componere\Definition::__construct(string `$name`, array `$interfaces`)
public function 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 function Componere\Patch::__construct(object `$instance`)
public function 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`.

function Componere\cast(string `$type`, object `$object`): object
function Componere\cast_by_ref(string `$type`, object `$object`): object

# インストール/設定

## 目次

- 要件
- インストール手順

## 要件

Reflection is required

## インストール手順

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 function addInterface(string `$interface`): Definition
public function addMethod(string `$name`, Componere\Method `$method`): Definition
public function addTrait(string `$trait`): Definition
public function getReflector(): ReflectionClass
}

# Componere\Abstract\Definition::addInterface

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addInterface — Add Interface

### 説明

public function 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

# Componere\Abstract\Definition::addMethod

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addMethod — Add Method

### 説明

public function 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

# Componere\Abstract\Definition::addTrait

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::addTrait — Add Trait

### 説明

public function 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

# Componere\Abstract\Definition::getReflector

(Componere 2 >= 2.1.0)

Componere\Abstract\Definition::getReflector — Reflection

### 説明

public function Componere\Abstract\Definition::getReflector(): ReflectionClass

Shall create or return a ReflectionClass

### 戻り値

A ReflectionClass for the current definition (cached)

## 目次

- Componere\Abstract\Definition::addInterface — Add Interface
- Componere\Abstract\Definition::addMethod — Add Method
- Componere\Abstract\Definition::addTrait — Add Trait
- Componere\Abstract\Definition::getReflector — Reflection

# 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 function __construct(string `$name`)
public function __construct(string `$name`, string `$parent`)
public function __construct(string `$name`, array `$interfaces`)
public function __construct(string `$name`, string `$parent`, array `$interfaces`)
/* メソッド */
public function addConstant(string `$name`, Componere\Value `$value`): Definition
public function addProperty(string `$name`, Componere\Value `$value`): Definition
public function register(): void
public function isRegistered(): bool
public function getClosure(string `$name`): Closure
public function getClosures(): array
/* 継承したメソッド */
public function Componere\Abstract\Definition::addInterface(string `$interface`): Definition
public function Componere\Abstract\Definition::addMethod(string `$name`, Componere\Method `$method`): Definition
public function Componere\Abstract\Definition::addTrait(string `$trait`): Definition
public function Componere\Abstract\Definition::getReflector(): ReflectionClass
}

# Componere\Definition::__construct

(Componere 2 >= 2.1.0)

Componere\Definition::__construct — Definition Construction

### 説明

public function Componere\Definition::__construct(string `$name`)
public function Componere\Definition::__construct(string `$name`, string `$parent`)
public function Componere\Definition::__construct(string `$name`, array `$interfaces`)
public function 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 a class in `interfaces` is not an interface

# Componere\Definition::addConstant

(Componere 2 >= 2.1.0)

Componere\Definition::addConstant — Add Constant

### 説明

public function 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

# Componere\Definition::addProperty

(Componere 2 >= 2.1.0)

Componere\Definition::addProperty — Add Property

### 説明

public function 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

# Componere\Definition::register

(Componere 2 >= 2.1.0)

Componere\Definition::register — Registration

### 説明

public function Componere\Definition::register(): void

Shall register the current Definition

### Exceptions

警告

Shall throw RuntimeException if Definition was registered

# Componere\Definition::isRegistered

(Componere 2 >= 2.1.0)

Componere\Definition::isRegistered — State Detection

### 説明

public function Componere\Definition::isRegistered(): bool

Shall detect the registration state of this Definition

### 戻り値

Shall return true if this Definition is registered

# Componere\Definition::getClosure

(Componere 2 >= 2.1.0)

Componere\Definition::getClosure — Get Closure

### 説明

public function 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

# Componere\Definition::getClosures

(Componere 2 >= 2.1.0)

Componere\Definition::getClosures — Get Closures

### 説明

public function 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

## 目次

- 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

# 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 function __construct(object `$instance`)
public function __construct(object `$instance`, array `$interfaces`)
/* メソッド */
public function apply(): void
public function revert(): void
public function isApplied(): bool
public function derive(object `$instance`): Patch
public function getClosure(string `$name`): Closure
public function getClosures(): array
/* 継承したメソッド */
public function Componere\Abstract\Definition::addInterface(string `$interface`): Definition
public function Componere\Abstract\Definition::addMethod(string `$name`, Componere\Method `$method`): Definition
public function Componere\Abstract\Definition::addTrait(string `$trait`): Definition
public function Componere\Abstract\Definition::getReflector(): ReflectionClass
}

# Componere\Patch::__construct

(Componere 2 >= 2.1.0)

Componere\Patch::__construct — Patch Construction

### 説明

public function Componere\Patch::__construct(object `$instance`)
public function 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 a class in `interfaces` is not an interface

# Componere\Patch::apply

(Componere 2 >= 2.1.0)

Componere\Patch::apply — Application

### 説明

public function Componere\Patch::apply(): void

Shall apply the current patch

# Componere\Patch::revert

(Componere 2 >= 2.1.0)

Componere\Patch::revert — Reversal

### 説明

public function Componere\Patch::revert(): void

Shall revert the current patch

# Componere\Patch::isApplied

(Componere 2 >= 2.1.0)

Componere\Patch::isApplied — State Detection

### 説明

public function Componere\Patch::isApplied(): bool

# Componere\Patch::derive

(Componere 2 >= 2.1.1)

Componere\Patch::derive — Patch Derivation

### 説明

public function 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

# Componere\Patch::getClosure

(Componere 2 >= 2.1.0)

Componere\Patch::getClosure — Get Closure

### 説明

public function 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

# Componere\Patch::getClosures

(Componere 2 >= 2.1.0)

Componere\Patch::getClosures — Get Closures

### 説明

public function 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

## 目次

- 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

# The Componere\Method class

(Componere 2 >= 2.1.0)

## はじめに

A Method represents a function with modifiable accessibility flags

## クラス概要

final class Componere\Method {
/* Constructor */
public function __construct(Closure `$closure`)
/* メソッド */
public function setPrivate(): Method
public function setProtected(): Method
public function setStatic(): Method
public function getReflector(): ReflectionMethod
}

# Componere\Method::__construct

(Componere 2 >= 2.1.0)

Componere\Method::__construct — Method Construction

### 説明

public function Componere\Method::__construct(Closure `$closure`)

### パラメータ

`closure`

# Componere\Method::setPrivate

(Componere 2 >= 2.1.0)

Componere\Method::setPrivate — Accessibility Modification

### 説明

public function Componere\Method::setPrivate(): Method

### 戻り値

The current Method

### Exceptions

警告

Shall throw RuntimeException if access level was previously set

# Componere\Method::setProtected

(Componere 2 >= 2.1.0)

Componere\Method::setProtected — Accessibility Modification

### 説明

public function Componere\Method::setProtected(): Method

### 戻り値

The current Method

### Exceptions

警告

Shall throw RuntimeException if access level was previously set

# Componere\Method::setStatic

(Componere 2 >= 2.1.0)

Componere\Method::setStatic — Accessibility Modification

### 説明

public function Componere\Method::setStatic(): Method

### 戻り値

The current Method

# Componere\Method::getReflector

(Componere 2 >= 2.1.0)

Componere\Method::getReflector — Reflection

### 説明

public function Componere\Method::getReflector(): ReflectionMethod

Shall create or return a ReflectionMethod

### 戻り値

A ReflectionMethod for the current method (cached)

## 目次

- Componere\Method::__construct — Method Construction
- Componere\Method::setPrivate — Accessibility Modification
- Componere\Method::setProtected — Accessibility Modification
- Componere\Method::setStatic — Accessibility Modification
- Componere\Method::getReflector — Reflection

# 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 function __construct(mixed `$default` = ?)
/* メソッド */
public function setPrivate(): Value
public function setProtected(): Value
public function setStatic(): Value
public function isPrivate(): bool
public function isProtected(): bool
public function isStatic(): bool
public function hasDefault(): bool
}

# Componere\Value::__construct

(Componere 2 >= 2.1.0)

Componere\Value::__construct — Value Construction

### 説明

public function Componere\Value::__construct(mixed `$default` = ?)

### パラメータ

`default`

### Exceptions

警告

Shall throw InvalidArgumentException if `default` does not have a suitable value

# Componere\Value::setPrivate

(Componere 2 >= 2.1.0)

Componere\Value::setPrivate — Accessibility Modification

### 説明

public function Componere\Value::setPrivate(): Value

### 戻り値

The current Value

### Exceptions

警告

Shall throw RuntimeException if access level was previously set

# Componere\Value::setProtected

(Componere 2 >= 2.1.0)

Componere\Value::setProtected — Accessibility Modification

### 説明

public function Componere\Value::setProtected(): Value

### 戻り値

The current Value

### Exceptions

警告

Shall throw RuntimeException if access level was previously set

# Componere\Value::setStatic

(Componere 2 >= 2.1.0)

Componere\Value::setStatic — Accessibility Modification

### 説明

public function Componere\Value::setStatic(): Value

### 戻り値

The current Value

# Componere\Value::isPrivate

(Componere 2 >= 2.1.0)

Componere\Value::isPrivate — Accessibility Detection

### 説明

public function Componere\Value::isPrivate(): bool

# Componere\Value::isProtected

(Componere 2 >= 2.1.0)

Componere\Value::isProtected — Accessibility Detection

### 説明

public function Componere\Value::isProtected(): bool

# Componere\Value::isStatic

(Componere 2 >= 2.1.0)

Componere\Value::isStatic — Accessibility Detection

### 説明

public function Componere\Value::isStatic(): bool

# Componere\Value::hasDefault

(Componere 2 >= 2.1.0)

Componere\Value::hasDefault — Value Interaction

### 説明

public function Componere\Value::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

# Componere 関数

# Componere\cast

(Componere 2 >= 2.1.2)

Componere\cast — Casting

### 説明

function Componere\cast(string `$type`, object `$object`): object

### パラメータ

`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

# Componere\cast_by_ref

(Componere 2 >= 2.1.2)

Componere\cast_by_ref — Casting

### 説明

function Componere\cast_by_ref(string `$type`, object `$object`): object

### パラメータ

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

## 目次

- Componere\cast — Casting
- Componere\cast_by_ref — Casting

- インストール/設定
  - 要件
  - インストール手順
- 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

# エラー処理およびログ記録

# はじめに

以下の関数は、エラー処理およびログ記録を行います。これらの関数によ り、独自のエラー処理規則を定義することが可能になり、同時にエラーの ログを記録する方法を修正することが可能になります。これにより、ニーズに 即したエラー出力の変更と拡張が可能になります。

ログ記録関数により他のマシンやemail(またはポケベルのゲートウエイ に!)、システムログ等に直接メッセージを送信することが可能になります。 これにより、ログを行うものを選択したり、アプリケーションやWebサイ トに最も重要な部分をモニタすることが可能になります。

エラー出力関数により、エラーのフィードバックのレベルと種類、 簡単な通知からカスタマイズされた関数までエラーの際に返すもの をカスタマイズすることが可能になります。

# インストール/設定

## 目次

- 実行時設定

## 実行時設定

php.ini の設定により動作が変化します。

エラーおよびロギング設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
--- | --- | --- | ---
error_reporting | NULL | `INI_ALL` |
fatal_error_backtraces | "1" | `INI_ALL` | PHP 8.5.0 以降で有効です。
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` | PHP 8.5.0 以降で非推奨です。
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` だけではなくすべてのエラーを含める) のような数を指定するようにしましょう。 これは現状の全ビットに対応した上で、かつ値が将来追加された場合にも対応できます。

`fatal_error_backtraces` bool
  致命的なエラーにバックトレースを含めるかどうかを制御します。 致命的なエラーとは、`E_ERROR`、 `E_CORE_ERROR`、`E_COMPILE_ERROR`、 `E_USER_ERROR`、 `E_RECOVERABLE_ERROR`、および `E_PARSE` のことです。
`display_errors` string

  エラーを出力の一部として画面に表示するか、ユーザーから隠すかを決めます。

  - `Off` - エラーを一切表示しません。
  - `On` または `stdout` - エラーを `stdout` に表示します。これがデフォルトです。
  - `stderr` - エラーを `stderr` に表示します。`CLI`、`phpdbg`、`CGI` の SAPI でのみ有効です。
  同梱されている `php.ini-development` ではこれを `On` に、`php.ini-production` では `Off` に設定しています。

  > 注意: 開発をサポートする仕組みであり、本番のシステムでは 使用すべきではありません (例えばインターネットに接続されたシステムなど)。

  > 注意:

  > 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` を有効にしている場合のみです。
  警告

  この機能は PHP 8.5.0 で 非推奨 になります。この機能に頼らないことを強く推奨します。

`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 では、対応する生の数値の代わりに定数名を使うことができます。 ただし、php.ini では `|`、 `~`、 `^`、 `!`、 `&` の演算子のみが解釈されます。

警告

PHP の外部では、シンボル名を使うことはできません。 例えば、httpd.conf の中では計算済みのビットマスク値を代わりに使わなければなりません。

`E_ERROR` (int)
  重大な実行時エラー。 これは、メモリ確保の問題といった復帰できないエラーを表します。 スクリプトの実行は中断されます。 定数の値：`1`
`E_WARNING` (int)
  実行時の警告 (致命的でないエラー)。 スクリプトの実行は中断されません。 定数の値：`2`
`E_PARSE` (int)
  コンパイル時のパースエラー。 パースエラーはパーサーでのみ生成されます。 定数の値：`4`
`E_NOTICE` (int)
  実行時の注意。 エラーを示しているかもしれない何かに遭遇したことを表します。 ただし、スクリプトを問題なく実行しているときに起こることもあります。 定数の値：`8`
`E_CORE_ERROR` (int)
  PHP の初期始動時点で発生した致命的なエラー。 `E_ERROR` に似ていますが、 PHP のコアによって生成される点が異なります。 定数の値：`16`
`E_CORE_WARNING` (int)
  PHP の初期始動時点で発生した (致命的でない) 警告。 `E_WARNING` に似ていますが、 PHP のコアによって生成される点が異なります。 定数の値：`32`
`E_COMPILE_ERROR` (int)
  コンパイル時の致命的なエラー。 `E_ERROR`に似ていますが、 Zend スクリプティングエンジンによって生成される点が異なります。 定数の値：`64`
`E_COMPILE_WARNING` (int)
  コンパイル時の (致命的でない) 警告。 `E_WARNING`に似ていますが、 Zend スクリプティングエンジンによって生成される点が異なります。 定数の値：`128`
`E_DEPRECATED` (int)
  実行時の非推奨の注意。 これを有効にすると、将来のバージョンで 動作しなくなるコードについての警告を受け取ることができます。 定数の値：`8192`
`E_USER_ERROR` (int)
  ユーザーによって生成されるエラーメッセージ。 `E_ERROR` に似ていますが、 trigger_error() 関数を用いて PHP コード上で 生成される点が異なります。 定数の値：`256`
  警告

  この定数を trigger_error() と使うのは PHP 8.4.0 で非推奨となりました。 代わりに、Exception を `throw` するか、 exit() を呼ぶことが推奨されます。

`E_USER_WARNING` (int)
  ユーザーによって生成される警告メッセージ。 `E_WARNING` に似ていますが、 trigger_error() 関数を用いて PHP コード上で 生成される点が異なります。 定数の値：`512`
`E_USER_NOTICE` (int)
  ユーザーによって生成される注意メッセージ。 `E_NOTICE` に似ていますが、 trigger_error() 関数を用いて PHP コード上で 生成される点が異なります。 定数の値：`1024`
`E_USER_DEPRECATED` (int)
  ユーザーによって生成される非推奨メッセージ。 `E_DEPRECATED` に似ていますが、 trigger_error() 関数を用いて PHP コード上で 生成される点が異なります。 定数の値：`16384`
`E_STRICT` (int)
  PHP が実行時に発行する提案。 コードの前方互換性を担保するために、実行中のコードについて改善が提案されます。 定数の値：`2048`
  警告

  このエラーレベルは使われておらず、 PHP 8.4.0 で非推奨となりました。

`E_RECOVERABLE_ERROR` (int)
  キャッチできる致命的なエラーに相当する従来のエンジン「例外」(訳注: この文脈での括弧付きの「例外」は、Error が登場するより前に用いられていた例外の「ような」仕組みを指したものです)。 Error に似ていますが、 ユーザー定義のエラーハンドラー (set_error_handler() を参照のこと) によってキャッチしなければなりません。 キャッチされなかった場合、`E_ERROR` と同様にスクリプトの実行を中断します。 定数の値：`4096`

  > 注意: このエラーレベルは実質的に使われていません。 唯一発生しうるのは、object を bool として解釈するのに失敗したときだけです。 これは、内部的なオブジェクトでしか起こりえません。 PHP 8.4.0 より前のバージョンにおける最もよくある例としては、 GMP インスタンスを条件式で使ったときです。

`E_ALL` (int)
  すべてのエラー、警告、注意を含んだビットマスク。 定数の値：`30719`
  警告

  PHP 8.4 より前のバージョンでは、 この定数の値は `32767` でした。

# 例

エラー処理機能を PHP で使用するための例を示します。 ファイルに(XML 形式で)情報を記録し、論理的に致命的なエラーの場合に、 開発者に電子メールを送信するようなエラー処理関数を定義します。

例1 スクリプト内でのエラー処理

    <?php
    // 自分のエラーハンドリングを行います
    error_reporting(0);

    // ユーザーの定義したエラーハンドリング関数
    function userErrorHandler($errno, $errmsg, $filename, $linenum, $vars)
    {
        // エラーエントリのタイムスタンプ
        $dt = date("Y-m-d H:i:s (T)");

        // エラー文字列の連想配列を定義します。
        // 実際のところ、考慮する必要があるのは
        // E_WARNING、E_NOTICE、E_USER_ERROR、
        // E_USER_WARNING そして E_USER_NOTICE だけです。
        $errortype = array (
                    E_ERROR              => 'Error',
                    E_WARNING            => 'Warning',
                    E_PARSE              => 'Parsing Error',
                    E_NOTICE             => 'Notice',
                    E_CORE_ERROR         => 'Core Error',
                    E_CORE_WARNING       => 'Core Warning',
                    E_COMPILE_ERROR      => 'Compile Error',
                    E_COMPILE_WARNING    => 'Compile Warning',
                    E_USER_ERROR         => 'User Error',
                    E_USER_WARNING       => 'User Warning',
                    E_USER_NOTICE        => 'User Notice',
                    E_STRICT             => 'Runtime Notice',
                    E_RECOVERABLE_ERROR  => 'Catchable Fatal Error'
                    );
        // set of errors for which a var trace will be saved
        $user_errors = array(E_USER_ERROR, E_USER_WARNING, E_USER_NOTICE);

        $err = "<errorentry>\n";
        $err .= "\t<datetime>" . $dt . "</datetime>\n";
        $err .= "\t<errornum>" . $errno . "</errornum>\n";
        $err .= "\t<errortype>" . $errortype[$errno] . "</errortype>\n";
        $err .= "\t<errormsg>" . $errmsg . "</errormsg>\n";
        $err .= "\t<scriptname>" . $filename . "</scriptname>\n";
        $err .= "\t<scriptlinenum>" . $linenum . "</scriptlinenum>\n";

        if (in_array($errno, $user_errors)) {
            $err .= "\t<vartrace>" . wddx_serialize_value($vars, "Variables") . "</vartrace>\n";
        }
        $err .= "</errorentry>\n\n";

        // テスト用
        // echo $err;

        // エラーログを保存し、重大なユーザーエラーは自分にメールする
        error_log($err, 3, "/usr/local/php4/error.log");
        if ($errno == E_USER_ERROR) {
            mail("phpdev@example.com", "Critical User Error", $err);
        }
    }

    function distance($vect1, $vect2)
    {
        if (!is_array($vect1) || !is_array($vect2)) {
            trigger_error("Incorrect parameters, arrays expected", E_USER_ERROR);
            return NULL;
        }

        if (count($vect1) != count($vect2)) {
            trigger_error("Vectors need to be of the same size", E_USER_ERROR);
            return NULL;
        }

        for ($i=0; $i<count($vect1); $i++) {
            $c1 = $vect1[$i]; $c2 = $vect2[$i];
            $d = 0.0;
            if (!is_numeric($c1)) {
                trigger_error("Coordinate $i in vector 1 is not a number, using zero",
                                E_USER_WARNING);
                $c1 = 0.0;
            }
            if (!is_numeric($c2)) {
                trigger_error("Coordinate $i in vector 2 is not a number, using zero",
                                E_USER_WARNING);
                $c2 = 0.0;
            }
            $d += $c2*$c2 - $c1*$c1;
        }
        return sqrt($d);
    }

    $old_error_handler = set_error_handler("userErrorHandler");

    // 未定義定数による警告の生成
    $t = I_AM_NOT_DEFINED;

    // いくつかの「ベクタ」定義
    $a = array(2, 3, "foo");
    $b = array(5.5, 4.3, -1.6);
    $c = array(1, -3);

    // ユーザーエラーの生成
    $t1 = distance($c, $b) . "\n";

    // 他のユーザーエラーの生成
    $t2 = distance($b, "i am not an array") . "\n";

    // 警告の生成
    $t3 = distance($a, $b) . "\n";

    ?>

# エラー処理関数

# 参考

syslog()も参照ください。

# debug_backtrace

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

debug_backtrace — バックトレースを生成する

### 説明

function 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(~DEBUG_BACKTRACE_PROVIDE_OBJECT)` | インデックス `"object"` を省略し、`"args"` を収集します。
  > `debug_backtrace(0)`
  > `debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS)` | インデックス `"object"` と `"args"` を 両方省略します。
  > `debug_backtrace(~DEBUG_BACKTRACE_PROVIDE_OBJECT | DEBUG_BACKTRACE_IGNORE_ARGS)`
  > `debug_backtrace(DEBUG_BACKTRACE_PROVIDE_OBJECT|DEBUG_BACKTRACE_IGNORE_ARGS)` | インデックス `"object"` を収集し、かつ `"args"` を省略します。

`limit`

  このパラメータを使ってスタックフレームの数を制限できます。 デフォルト (`limit`=`0`) は、すべてのスタックフレームを返します。

### 戻り値

連想配列(array)の配列を返します。連想配列の要素として返される可能性があるものは以下のとおりです。

debug_backtrace() から返される可能性がある要素
名前 | 型 | 説明
--- | --- | ---
function | string | カレントの関数名。 __FUNCTION__ も参照ください。
line | int | カレントの行番号。 __LINE__ も参照ください。
file | string | カレントのファイル名。 __FILE__ も参照ください。
class | string | カレントのクラス名。 __CLASS__ も参照ください。
object | object | `DEBUG_BACKTRACE_PROVIDE_OBJECT` が指定されている場合、カレントのオブジェクト。
type | string | カレントのコール方式。メソッドを呼び出している場合は "->"、 staticメソッドを呼び出している場合は "::" が返されます。 関数呼び出しの場合は何も返されません。
args | array | 関数の内部の場合、関数の引数のリストとなります。 インクルードされたファイル内では、 読み込まれたファイルの名前となります。 ただし、`DEBUG_BACKTRACE_IGNORE_ARGS` が指定されている場合を除きます。

### 例

例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_print_backtrace

(PHP 5, PHP 7, PHP 8)

debug_print_backtrace — バックトレースを表示する

### 説明

function 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() - バックトレースを生成する

# error_clear_last

(PHP 7, PHP 8)

error_clear_last — 最も最近のエラーをクリア

### 説明

function 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_get_last

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

error_get_last — 最後に発生したエラーを取得する

### 説明

function 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_log

(PHP 4, PHP 5, PHP 7, PHP 8)

error_log — 定義されたエラー処理ルーチンにエラーメッセージを送信する

### 説明

function 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() に渡す必要があります。

# error_reporting

(PHP 4, PHP 5, PHP 7, PHP 8)

error_reporting — 出力する PHP エラーの種類を設定する

### 説明

function 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() - 設定オプションの値を設定する

# get_error_handler

(PHP 8 >= 8.5.0)

get_error_handler — ユーザー定義のエラーハンドラ関数を取得する

### 説明

function get_error_handler(): ?callable

存在する場合に、現在のエラーハンドラ関数を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

(もしあれば)現在定義済みのエラーハンドラを返します。 組み込みのエラーハンドラを使っている場合は、`null` を返します。

返されたエラーハンドラは、 set_error_handler() に渡された callable そのものです。

### 例

例1 get_error_handler() の例

    <?php

    $handler = function (int $errno, string $errstr, ?string $errfile, ?int $errline) {
         echo "Error: " . $errstr . "\n";
    };

    var_dump(get_error_handler()); // NULL

    set_error_handler($handler);

    var_dump(get_error_handler() === $handler); // bool(true)

    ?>

### 注意

ヒント

PHP 8.5.0 より前のバージョンでは、 この関数の機能は以下のような polyfill で提供できます:

    <?php
    if (!function_exists('get_error_handler')) {
        function noop_error_handler() {
        }
        function get_error_handler(): ?callable {
            $handler = set_error_handler('noop_error_handler');
            restore_error_handler();
            return $handler;
        }
    }
    ?>

### 参考

- error_reporting() - 出力する PHP エラーの種類を設定する
- set_error_handler() - ユーザー定義のエラーハンドラ関数を設定する
- restore_error_handler() - 以前のエラーハンドラ関数を回復する
- trigger_error() - ユーザーレベルのエラー/警告/通知メッセージを生成する
- エラーレベル定数

# get_exception_handler

(PHP 8 >= 8.5.0)

get_exception_handler — ユーザー定義の例外ハンドラ関数を取得する

### 説明

function get_exception_handler(): ?callable

存在する場合に、現在の例外ハンドラ関数を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

現在定義済みの例外ハンドラを返します。 ハンドラが定義されていない場合は、`null` を返します。

返されたハンドラは、 set_exception_handler() に渡された callable そのものです。

### 例

例1 get_exception_handler() の例

    <?php

    $handler = function (Throwable $ex) {
         echo "Exception: " . $ex::class . ": " . $ex->getMessage() . "\n";
    };

    var_dump(get_exception_handler()); // NULL

    set_exception_handler($handler);

    var_dump(get_exception_handler() === $handler); // bool(true)

    ?>

### 注意

ヒント

PHP 8.5.0 より前のバージョンでは、 この関数の機能は以下のような polyfill で提供できます:

    <?php
    if (!function_exists('get_exception_handler')) {
        function noop_exception_handler() {
        }
        function get_exception_handler(): ?callable {
            $handler = set_exception_handler('noop_exception_handler');
            restore_exception_handler();
            return $handler;
        }
    }
    ?>

### 参考

- set_exception_handler() - ユーザー定義の例外ハンドラ関数を設定する
- restore_exception_handler() - 以前の例外ハンドラ関数を回復する
- restore_error_handler() - 以前のエラーハンドラ関数を回復する
- error_reporting() - 出力する PHP エラーの種類を設定する
- Exceptions

# restore_error_handler

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

restore_error_handler — 以前のエラーハンドラ関数を回復する

### 説明

function 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() - ユーザー定義のエラーハンドラ関数を設定する
- get_error_handler() - ユーザー定義のエラーハンドラ関数を取得する
- restore_exception_handler() - 以前の例外ハンドラ関数を回復する
- trigger_error() - ユーザーレベルのエラー/警告/通知メッセージを生成する

# restore_exception_handler

(PHP 5, PHP 7, PHP 8)

restore_exception_handler — 以前の例外ハンドラ関数を回復する

### 説明

function 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() - ユーザー定義の例外ハンドラ関数を設定する
- get_exception_handler() - ユーザー定義の例外ハンドラ関数を取得する
- set_error_handler() - ユーザー定義のエラーハンドラ関数を設定する
- restore_error_handler() - 以前のエラーハンドラ関数を回復する
- error_reporting() - 出力する PHP エラーの種類を設定する

# set_error_handler

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

set_error_handler — ユーザー定義のエラーハンドラ関数を設定する

### 説明

function 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` を渡すと、ハンドラをデフォルトの状態に戻せます。 それ以外の場合、次のシグネチャに従うコールバックを渡します:

  function 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 の設定によらず 全てのエラーに関してコールされます。

### 戻り値

前に定義されたエラーハンドラ(ある場合)を callable として返します。 組み込みのエラーハンドラを使用している場合は `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 false;
        }

        // $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() - 以前のエラーハンドラ関数を回復する
- get_error_handler() - ユーザー定義のエラーハンドラ関数を取得する
- trigger_error() - ユーザーレベルのエラー/警告/通知メッセージを生成する
- エラーレベル定数

# set_exception_handler

(PHP 5, PHP 7, PHP 8)

set_exception_handler — ユーザー定義の例外ハンドラ関数を設定する

### 説明

function set_exception_handler(?callable `$callback`): ?callable

例外が try/catch ブロックの中でキャッチされなかった場合の デフォルトの例外ハンドラを設定します。 実行は、`callback` がコールされた後に 停止します。

### パラメータ

`callback`

  キャッチされない例外が発生した際にコールされる関数。 このハンドラ関数は、スローされる Throwable オブジェクトを引数にとります。 Error と Exception は、 どちらも Throwable インターフェイスを実装しています。 ハンドラのシグネチャは、次のようになります。

  function 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";
    ?>

### 参考

- get_exception_handler() - ユーザー定義の例外ハンドラ関数を取得する
- restore_exception_handler() - 以前の例外ハンドラ関数を回復する
- restore_error_handler() - 以前のエラーハンドラ関数を回復する
- error_reporting() - 出力する PHP エラーの種類を設定する
- 例外(exceptions)

# trigger_error

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

trigger_error — ユーザーレベルのエラー/警告/通知メッセージを生成する

### 説明

function trigger_error(string `$message`, int `$error_level` = `E_USER_NOTICE`): true

ユーザーエラーを発生させるために使います。組み込みのエラーハンドラまたは新しいエラーハンドラ (set_error_handler()) として設定済みのユーザー定義関数と組み合わせて使うこともできます。

この関数は、実行時の例外に特定の応答を生成する必要がある場合に便利です。

### パラメータ

`message`

  このエラーに割り当てられたメッセージ。長さは最大 1024 バイトまでです。1024 バイトを超える部分は切り捨てられます。

`error_level`

  このエラーに割り当てられたエラー型です。`E_USER_*` の定数のみが指定可能で、デフォルトは `E_USER_NOTICE` です。

  警告

  `error_level` として `E_USER_ERROR` を指定するのは非推奨となりました。 かわりに、Exception をスローするか、 exit() を呼び出してください。

### 戻り値

常に `true` を返します。

### エラー / 例外

`error_level` が `E_USER_ERROR`, `E_USER_WARNING`, `E_USER_NOTICE`, `E_USER_DEPRECATED` のいずれかでない場合、この関数は ValueError をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `error_level` として `E_USER_ERROR` を指定するのは非推奨となりました。 かわりに、Exception をスローするか、 exit() を呼び出してください。
8.4.0 | 戻り値の型が、bool ではなく true に変更されました。
8.0.0 | 不正な `error_level` を指定すると、ValueError をスローするようになりました。 これより前のバージョンでは、`false` を返していました。

### 例

例1 trigger_error() の例

より拡張した例については set_error_handler() を参照ください。

    <?php
    $password = $_POST['password'] ?? '';
    if ($password === '') {
      trigger_error("空のパスワードを使用することは安全ではありません", E_USER_WARNING);
    }
    $hash = password_hash($password, PASSWORD_DEFAULT);
    ?>

### 注意

警告

`message` の HTML エンティティはエスケープされません。エラーをブラウザに表示するのであれば、メッセージに htmlentities() を使います。

### 参考

- error_reporting() - 出力する PHP エラーの種類を設定する
- set_error_handler() - ユーザー定義のエラーハンドラ関数を設定する
- restore_error_handler() - 以前のエラーハンドラ関数を回復する
- エラーレベル定数
- Deprecated アトリビュート

# user_error

(PHP 4, PHP 5, PHP 7, PHP 8)

user_error — trigger_error() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 trigger_error().

## 目次

- debug_backtrace — バックトレースを生成する
- debug_print_backtrace — バックトレースを表示する
- error_clear_last — 最も最近のエラーをクリア
- error_get_last — 最後に発生したエラーを取得する
- error_log — 定義されたエラー処理ルーチンにエラーメッセージを送信する
- error_reporting — 出力する PHP エラーの種類を設定する
- get_error_handler — ユーザー定義のエラーハンドラ関数を取得する
- get_exception_handler — ユーザー定義の例外ハンドラ関数を取得する
- restore_error_handler — 以前のエラーハンドラ関数を回復する
- restore_exception_handler — 以前の例外ハンドラ関数を回復する
- set_error_handler — ユーザー定義のエラーハンドラ関数を設定する
- set_exception_handler — ユーザー定義の例外ハンドラ関数を設定する
- trigger_error — ユーザーレベルのエラー/警告/通知メッセージを生成する
- user_error — trigger_error のエイリアス

- インストール/設定
  - 実行時設定
- 定義済み定数
- 例
- エラー処理関数
  - debug_backtrace — バックトレースを生成する
  - debug_print_backtrace — バックトレースを表示する
  - error_clear_last — 最も最近のエラーをクリア
  - error_get_last — 最後に発生したエラーを取得する
  - error_log — 定義されたエラー処理ルーチンにエラーメッセージを送信する
  - error_reporting — 出力する PHP エラーの種類を設定する
  - get_error_handler — ユーザー定義のエラーハンドラ関数を取得する
  - get_exception_handler — ユーザー定義の例外ハンドラ関数を取得する
  - restore_error_handler — 以前のエラーハンドラ関数を回復する
  - restore_exception_handler — 以前の例外ハンドラ関数を回復する
  - set_error_handler — ユーザー定義のエラーハンドラ関数を設定する
  - set_exception_handler — ユーザー定義の例外ハンドラ関数を設定する
  - trigger_error — ユーザーレベルのエラー/警告/通知メッセージを生成する
  - user_error — trigger_error のエイリアス

# 外部関数インターフェース

# はじめに

この拡張は、Zend 拡張 API の深い知識が無くとも、あるいは第三の中間言語を学ぶことをせずとも、 純粋な PHP で共有ライブラリ (.DLL または .so) を読み込んだり、C の関数を呼び出したり、C のデータ構造にアクセスしたりすることを 可能とします。 公開 API は単一のクラス FFI として実装されています。 このクラスの static メソッド (そのうちのいくつかは非 static メソッドとしても呼び出せます) や オーバーロードされたオブジェクトメソッドが、実際の C のデータとのやり取りを行います。

警告

FFI は、システムと低レベルでやり取りできるため危険です。 FFI 拡張は、C 言語および使用する C API についての実用的な知識を持つ開発者のみが 用いるべきです。リスクを最小化するため、FFI API の使用は ffi.enable php.ini ディレクティブによって制限できます。

> 注意: FFI 拡張は、古くからある PHP 拡張の API を廃止しようとしているわけではなく、 C の関数やデータ構造へのアドホックなインターフェースを提供するにすぎません。

ヒント

今のところ、FFI のデータ構造へのアクセスは、ネイティブな PHP の配列やオブジェクトへのアクセスと比べて 非常に (約 2 倍) 低速です。したがって、速度のために FFI 拡張を使うことには意味がありません。 しかし、メモリ消費を減らすために使うのは意味があるかもしれません。

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定

## 要件

この拡張には、» libffi library の インストールが必要です。

## インストール手順

FFI 拡張を有効にするには、 --with-ffi を付けて PHP をビルドする必要があります。

Windows ユーザーが FFI 拡張を有効にするには、 php.ini に php_ffi.dll を含める必要があります。

## 実行時設定

php.ini の設定により動作が変化します。

FFI 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
--- | --- | --- | ---
ffi.enable | "preload" | `INI_SYSTEM` |
ffi.preload | "" | `INI_SYSTEM` |

INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

`ffi.enable` string
  FFI API の使用を有効化する (`"true"`) か 無効化する (`"false"`) か、 CLI SAPI と事前ロードファイルでだけ使えるよう制限する (`"preload"`) かを 指定します。 FFI API の利用制限は、FFI クラスにのみ影響し、 FFI\CData オブジェクトのオーバーロードされた関数には影響しません。 つまり、事前ロードファイルで FFI\CData オブジェクトを作成し、 それを PHP スクリプトで直接使うことは可能だということです。
`ffi.preload` string
  FFI バインディングを起動時に事前ロードできるようにします。 opcache.preload_user が設定されている場合、 FFI の事前ロードを FFI::load() で実現することはできません。 このディレクティブは `DIRECTORY_SEPARATOR` で区切られたファイル名のリストを受け付けます。 事前ロードされたバインディングは FFI::scope() を呼ぶことでアクセスできます。

# 例

## 目次

- FFI の基本的な使い方
- PHP のコールバック
- PHP/FFI/事前ロードの完全な例

## FFI の基本的な使い方

FFI API の詳細に深く立ち入る前に、よくあるタスクに対する FFI API の使い方が どれほど簡単かを示す例をいくつか見てみましょう。

> 注意: これらの例の中には、libc.so.6 を必要とするものがあります。 それらは、このライブラリが利用できないシステムでは動きません。

例1 共有ライブラリの関数を呼ぶ

    <?php
    // FFI オブジェクトを作成し、libc を読み込んで printf() 関数をエクスポートする
    $ffi = FFI::cdef(
        "int printf(const char *format, ...);", // ここは通常の C の宣言
        "libc.so.6");
    // C の printf() を呼ぶ
    $ffi->printf("Hello %s!\n", "world");
    ?>

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

    Hello world!

> 注意: C の関数のうちのいくつかは、特定の呼び出し規約 (例: `__fastcall`、 `__stdcall`、`,__vectorcall` など) を必要とすることに注意してください。

例2 関数を呼び出し、構造体を引数経由で返す

    <?php
    // gettimeofday() のバインディングを作成する
    $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");
    // C のデータ構造を作成する
    $tv = $ffi->new("struct timeval");
    $tz = $ffi->new("struct timezone");
    // C の gettimeofday() を呼ぶ
    var_dump($ffi->gettimeofday(FFI::addr($tv), FFI::addr($tz)));
    // C のデータ構造のフィールドにアクセスする
    var_dump($tv->tv_sec);
    // C のデータ構造全体を出力する
    var_dump($tz);
    ?>

上の例の出力は、 たとえば以下のようになります。

    int(0)
    int(1555946835)
    object(FFI\CData:struct timezone)#3 (2) {
      ["tz_minuteswest"]=>
      int(0)
      ["tz_dsttime"]=>
      int(0)
    }

例3 既存の C の変数にアクセスする

    <?php
    // FFI オブジェクトを作成し、libc を読み込んで errno 変数をエクスポートする
    $ffi = FFI::cdef(
        "int errno;", // ここは通常の C の宣言
        "libc.so.6");
    // C の errno を出力する
    var_dump($ffi->errno);
    ?>

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

    int(0)

例4 C の変数を作成して書き換える

    <?php
    // 新しい C の int 変数を作成する
    $x = FFI::new("int");
    var_dump($x->cdata);

    // 単純な代入
    $x->cdata = 5;
    var_dump($x->cdata);

    // 複合代入
    $x->cdata += 2;
    var_dump($x->cdata);
    ?>

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

    int(0)
    int(5)
    int(7)

例5 C の配列を扱う

    <?php
    // C のデータ構造を作成する
    $a = FFI::new("long[1024]");
    // 通常の PHP の配列を扱うのと同じように扱う
    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 C の enum を扱う

    <?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 のコールバック

PHP のクロージャを、関数ポインタ型のネイティブ変数に代入したり、 関数の引数として渡したりできます。

例1 PHP の Closure を C の関数ポインタに代入する

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

これは動作こそしますが、この機能は libffi が動作するすべてのプラットフォームでサポートされているわけではありません。 また、非効率的であり、リクエストの終了時にリソースがリークします。
ヒント

したがって、PHP のコールバックの使用は最小限にすることを推奨します。

## PHP/FFI/事前ロードの完全な例

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");
    ?>

# C のコードやデータへの主要インターフェース

(PHP 7 >= 7.4.0, PHP 8)

## はじめに

このクラスのオブジェクトは、ファクトリーメソッドである FFI::cdef() や FFI::load()、FFI::scope() によって作成されます。 定義された C の変数は FFI インスタンスのプロパティとして利用可能となり、 定義された C の関数は FFI インスタンスのメソッドとして利用可能となります。 宣言された C の型は、FFI::new() や FFI::type() を使って 新しい C のデータ構造を作成するのに使用できます。

FFI 定義のパースや共有ライブラリの読み込みには長い時間がかかることがあります。 Web 環境において、各 HTTP リクエストでこれを行うのは不便です。 しかし、FFI 定義やライブラリを PHP の起動時に事前ロードし、FFI オブジェクトを必要なときにインスタンス化することが可能です。 ヘッダーファイルは特殊な define である `FFI_SCOPE` によって拡張することができ (例: `#define FFI_SCOPE "foo"`。デフォルトのスコープは "C" です)、 事前ロード中に FFI::load() によって読み込むことができます。 これによって、永続的なバインディングが作成されます。 こうして作られたバインディングは、FFI::scope() を通じて後続する全リクエストで利用可能となります。 詳しくは PHP/FFI/事前ロードの完全な例 を参照してください。

複数の C のヘッダーファイルを同一のスコープへと事前ロードできます。

## クラス概要

final class FFI {
/* 定数 */
public const int __BIGGEST_ALIGNMENT__;
/* メソッド */
public static function addr(FFI\CData `&$ptr`): FFI\CData
public static function alignof(FFI\CData|FFI\CType `&$ptr`): int
public static function arrayType(FFI\CType `$type`, array `$dimensions`): FFI\CType
public function cast(FFI\CType|string `$type`, FFI\CData|int|float|bool|null `&$ptr`): ?FFI\CData
public static function cdef(string `$code` = "", ?string `$lib` = `null`): FFI
public static function free(FFI\CData `&$ptr`): void
public static function isNull(FFI\CData `&$ptr`): bool
public static function load(string `$filename`): ?FFI
public static function memcmp(string|FFI\CData `&$ptr1`, string|FFI\CData `&$ptr2`, int `$size`): int
public static function memcpy(FFI\CData `&$to`, FFI\CData|string `&$from`, int `$size`): void
public static function memset(FFI\CData `&$ptr`, int `$value`, int `$size`): void
public function new(FFI\CType|string `$type`, bool `$owned` = `true`, bool `$persistent` = `false`): ?FFI\CData
public static function scope(string `$name`): FFI
public static function sizeof(FFI\CData|FFI\CType `&$ptr`): int
public static function string(FFI\CData `&$ptr`, ?int `$size` = `null`): string
public function type(string `$type`): ?FFI\CType
public static function typeof(FFI\CData `&$ptr`): FFI\CType
}

## 定義済み定数

`FFI::__BIGGEST_ALIGNMENT__`

# FFI::addr

(PHP 7 >= 7.4.0, PHP 8)

FFI::addr — C のデータへのアンマネージドなポインターを作成する

### 説明

public static function FFI::addr(FFI\CData `&$ptr`): FFI\CData

与えられた FFI\CData によって表される C のデータへの アンマネージドなポインターを作成します。元になる `ptr` は返されるポインターよりも長く生存しなければなりません。 この関数は、主に C の関数へ引数をポインタ経由で渡すのに便利です。

### パラメータ

`ptr`
  C のデータ構造へのポインターのハンドル。

### 戻り値

新しく作成された FFI\CData オブジェクトを返します。

# FFI::alignof

(PHP 7 >= 7.4.0, PHP 8)

FFI::alignof — アラインメントを取得する

### 説明

public static function FFI::alignof(FFI\CData|FFI\CType `&$ptr`): int

与えられた FFI\CData オブジェクトまたは FFI\CType オブジェクトのアラインメントを返します。

### パラメータ

`ptr`
  C のデータまたは C の型のハンドル。

### 戻り値

与えられた FFI\CData オブジェクトまたは FFI\CType オブジェクトのアラインメントを返します。

# FFI::arrayType

(PHP 7 >= 7.4.0, PHP 8)

FFI::arrayType — 新しい C の配列型を動的に構築する

### 説明

public static function FFI::arrayType(FFI\CType `$type`, array `$dimensions`): FFI\CType

`type` で指定された要素型と `dimensions` で指定された次元を持つ 新しい C の配列型を動的に構築します。以下の例において `$t1` と `$t2` は等しい配列型です。

    <?php
    $t1 = FFI::type("int[2][3]");
    $t2 = FFI::arrayType(FFI::type("int"), [2, 3]);
    ?>

### パラメータ

`type`
  有効な C の宣言を表す string か、作成済みの FFI\CType のインスタンス。
`dimensions`
  型の次元を表す array。

### 戻り値

新しく作成した FFI\CType オブジェクトを返します。

# FFI::cast

(PHP 7 >= 7.4.0, PHP 8)

FFI::cast — C の型キャストを実行する

### 説明

public function FFI::cast(FFI\CType|string `$type`, FFI\CData|int|float|bool|null `&$ptr`): ?FFI\CData

FFI::cast() は、同じ C のデータ構造を参照するものの別の型が紐付けられた FFI\CData オブジェクトを新しく作成します。 返却されるオブジェクトはその C のデータを所有しません。元の `ptr` は その返り値よりも長く生存する必要があります。 C の型は、有効な C の型宣言を表す string として指定するか、 以前作成した FFI\CType オブジェクトとして指定します。 このインスタンスで宣言された任意の型が使えます。

### パラメータ

`type`
  有効な C の宣言を表す string か、作成済みの FFI\CType のインスタンス。
`ptr`
  C のデータ構造へのポインターのハンドル。

### 戻り値

新しく作成された FFI\CData オブジェクトを返します。

### 変更履歴

バージョン | 説明
--- | ---
8.3.0 | FFI::cast() を static メソッドとして呼び出すのは非推奨となりました。

# FFI::cdef

(PHP 7 >= 7.4.0, PHP 8)

FFI::cdef — 新しい FFI オブジェクトを作成する

### 説明

public static function FFI::cdef(string `$code` = "", ?string `$lib` = `null`): FFI

新しい FFI オブジェクトを作成します。

### パラメータ

`code`
  通常の C 言語の宣言 (型、構造体、関数、変数など) を含む文字列。 実際には、この文字列は C のヘッダーファイルからコピーペーストしてきたものかもしれません。

  > 注意: C のプリプロセッサーディレクティブはサポートされていません。 例えば、`#include` や `#define`、プリプロセッサーマクロは動作しません。

`lib`
  共有ライブラリの名前。 ここで指定したライブラリが読み込まれ、与えた定義とリンクされます。

  > 注意: `lib` を省略したり `null` を渡したりすると、 `RTLD_DEFAULT` をサポートしているプラットフォームでは、 通常のグローバルスコープから `code` で宣言されているシンボルを探索しようとします。 そうでないシステムでは、シンボルの解決に失敗します。

### 戻り値

新しく作成された FFI オブジェクトを返します。

### 変更履歴

バージョン | 説明
--- | ---
8.3.0 | `void` を返す C の関数が、FFI\CType::TYPE_VOID ではなく PHP の null を返すようになりました。
8.0.0 | `lib` は、nullable になりました。

# FFI::free

(PHP 7 >= 7.4.0, PHP 8)

FFI::free — アンマネージドなデータ構造を解放する

### 説明

public static function FFI::free(FFI\CData `&$ptr`): void

以前に作成されたアンマネージドなデータ構造を手で解放します。

### パラメータ

`ptr`
  C のデータ構造へのアンマネージドなポインターのハンドル。

### 戻り値

値を返しません。

# FFI::isNull

(PHP 7 >= 7.4.0, PHP 8)

FFI::isNull — FFI\CData が NULL ポインターかどうかを調べる

### 説明

public static function FFI::isNull(FFI\CData `&$ptr`): bool

FFI\CData が NULL ポインターかどうかを調べます。

### パラメータ

`ptr`
  C のデータ構造へのポインターのハンドル。

### 戻り値

FFI\CData が NULL ポインターかどうかを返します。

# FFI::load

(PHP 7 >= 7.4.0, PHP 8)

FFI::load — C のヘッダーファイルから C の宣言を読み込む

### 説明

public static function FFI::load(string `$filename`): ?FFI

C のヘッダーファイルから C の宣言を読み込みます。 読み込まれる C のヘッダーファイル内で特殊な define `FFI_LIB` を使うことで、 読み込む共有ライブラリを指定することが可能です。

### パラメータ

`filename`
  C のヘッダーファイル名。 C のプリプロセッサーディレクティブはサポートされていません。 例えば、`#include` や `#define`、プリプロセッサーマクロは動作しません。 ただし、次に挙げる特殊な場合を除きます。 このヘッダーファイルでは、`#define` 文で `FFI_SCOPE` 変数を定義すべきです (例: `#define FFI_SCOPE "MYLIB"`)。 詳しくは FFI クラスの概要 を参照してください。 このヘッダーファイルでは、`#define` 文で `FFI_LIB` 変数を定義することで、公開するライブラリを指定しても構いません。 それがシステムライブラリなら、必要なのはファイル名だけです (例: `#define FFI_LIB "libc.so.6"`)。カスタムライブラリなら、相対パスが必要です (例: `#define FFI_LIB "./mylib.so"`)。

### 戻り値

新しく作成された FFI オブジェクトを返します。 失敗時には `null` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.3.0 | 現在のシステムユーザが `opcache.preload_user` 設定ディレクティブで定義されたユーザと同じである場合、 事前ロードスクリプト の中で FFI::load() を呼べるようになりました。

### 参考

- FFI::scope() - 事前ロード中にパースされた C の宣言を使って FFI オブジェクトをインスタンス化する

# FFI::memcmp

(PHP 7 >= 7.4.0, PHP 8)

FFI::memcmp — メモリ領域を比較する

### 説明

public static function FFI::memcmp(string|FFI\CData `&$ptr1`, string|FFI\CData `&$ptr2`, int `$size`): int

メモリ領域 `ptr1` と `ptr2` を `size` バイト分比較します。 `ptr1` も `ptr2` も、 ネイティブデータ構造 (FFI\CData) または PHP の string にできます。

### パラメータ

`ptr1`
  一方のメモリ領域の開始位置。
`ptr2`
  もう一方のメモリ領域の開始位置。
`size`
  比較するバイト数。

### 戻り値

`ptr1` から始まるメモリ領域の中身が `ptr2` から始まるメモリ領域の中身より小さければ、 `0` より小さい値を返します。 `ptr1` が `ptr2` より大きければ、 `0` より大きい値を返します。 両者が等しければ `0` を返します。

# FFI::memcpy

(PHP 7 >= 7.4.0, PHP 8)

FFI::memcpy — あるメモリ領域を別の領域へコピーする

### 説明

public static function FFI::memcpy(FFI\CData `&$to`, FFI\CData|string `&$from`, int `$size`): void

`from` のメモリ領域から `size` バイト分を `to` のメモリ領域へとコピーします。

### パラメータ

`to`
  コピー先のメモリ領域の開始位置。
`from`
  コピー元のメモリ領域の開始位置。
`size`
  コピーするバイト数。

### 戻り値

値を返しません。

# FFI::memset

(PHP 7 >= 7.4.0, PHP 8)

FFI::memset — メモリ領域を埋める

### 説明

public static function FFI::memset(FFI\CData `&$ptr`, int `$value`, int `$size`): void

`ptr` が指すメモリ領域を `size` バイト分 与えられた `value` で埋めます。

### パラメータ

`ptr`
  埋めるメモリ領域の開始位置。
`value`
  埋めるのに使うバイト。
`size`
  埋めるバイト数。

### 戻り値

値を返しません。

# FFI::new

(PHP 7 >= 7.4.0, PHP 8)

FFI::new — C のデータ構造を作成する

### 説明

public function FFI::new(FFI\CType|string `$type`, bool `$owned` = `true`, bool `$persistent` = `false`): ?FFI\CData

与えられた C の型を持つネイティブデータ構造を作成します。 このインスタンスで宣言された任意の型が使えます。

### パラメータ

`type`
  `type` は、有効な C の宣言を表す string か、 作成済みの FFI\CType のインスタンスです。
`owned`
  所有された (マネージドな) データを作成するか、アンマネージドなデータを作成するか。 マネージドデータは返される FFI\CData オブジェクトと共に生存し、 そのオブジェクトへの最後の参照が PHP の通常のリファレンスカウントや GC によって解放されたときに解放されます。 アンマネージドなデータは、不要になったら FFI::free() を呼んで解放すべきです。
`persistent`
  この C のデータ構造をシステムヒープ上に永続的に確保するか (malloc() を使用)、 PHP のリクエストヒープ上に確保するか (emalloc() を使用)。

### 戻り値

新しく作成された FFI\CData オブジェクトを返します。 失敗時には `null` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.3.0 | FFI::new() を static メソッドとして呼び出すのは非推奨となりました。

# FFI::scope

(PHP 7 >= 7.4.0, PHP 8)

FFI::scope — 事前ロード中にパースされた C の宣言を使って FFI オブジェクトをインスタンス化する

### 説明

public static function FFI::scope(string `$name`): FFI

事前ロード中にパースされた C の宣言を使って FFI オブジェクトをインスタンス化します。

FFI::scope() メソッドを同じスコープに対して複数回呼んでも安全です。 同じスコープを指す複数の参照は同時に読み込まれるかもしれません。

### パラメータ

`name`
  特殊な `FFI_SCOPE` define によって定義されたスコープ名。

### 戻り値

新しく作成された FFI オブジェクトを返します。

### 参考

- FFI::load() - C のヘッダーファイルから C の宣言を読み込む

# FFI::sizeof

(PHP 7 >= 7.4.0, PHP 8)

FFI::sizeof — C のデータサイズまたは C の型サイズを取得する

### 説明

public static function FFI::sizeof(FFI\CData|FFI\CType `&$ptr`): int

与えられた FFI\CData オブジェクトまたは FFI\CType オブジェクトのサイズを返します。

### パラメータ

`ptr`
  C のデータまたは C の型のハンドル。

### 戻り値

`ptr` が指すメモリ領域のサイズ。

# FFI::string

(PHP 7 >= 7.4.0, PHP 8)

FFI::string — メモリ領域から PHP の文字列を作成する

### 説明

public static function FFI::string(FFI\CData `&$ptr`, ?int `$size` = `null`): string

`ptr` が指すメモリ領域の `size` バイト分から PHP の string を作成します。

### パラメータ

`ptr`
  string を作成する元となるメモリ領域の開始位置。
`size`
  string へコピーするバイト数。 `size` を省略したり `null` を指定したりする場合、 `ptr` はゼロ終端された C の `char` 配列でなければなりません。

### 戻り値

新しく作成された PHP の string。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `size` が nullable になりました。以前は `0` がデフォルトでした。

# FFI::type

(PHP 7 >= 7.4.0, PHP 8)

FFI::type — C の宣言から FFI\CType オブジェクトを作成する

### 説明

public function FFI::type(string `$type`): ?FFI\CType

この関数は、C の型宣言を持つ string を渡すと、 与えられた string に対応する FFI\CType オブジェクトを作成して返します。 このインスタンスで宣言された任意の型が使えます。

### パラメータ

`type`
  有効な C の宣言を持つ string。

### 戻り値

新しく作成された FFI\CType オブジェクトを返します。 失敗時には `null` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.3.0 | FFI::type() を static メソッドとして呼び出すのは非推奨となりました。

# FFI::typeof

(PHP 7 >= 7.4.0, PHP 8)

FFI::typeof — FFI\CData の FFI\CType を取得する

### 説明

public static function FFI::typeof(FFI\CData `&$ptr`): FFI\CType

与えられた FFI\CData オブジェクトの型を表す FFI\CType オブジェクトを取得します。

### パラメータ

`ptr`
  C のデータ構造へのポインターのハンドル。

### 戻り値

与えられた FFI\CData オブジェクトの型を表す FFI\CType オブジェクトを返します。

## 目次

- FFI::addr — C のデータへのアンマネージドなポインターを作成する
- FFI::alignof — アラインメントを取得する
- FFI::arrayType — 新しい C の配列型を動的に構築する
- FFI::cast — C の型キャストを実行する
- FFI::cdef — 新しい FFI オブジェクトを作成する
- FFI::free — アンマネージドなデータ構造を解放する
- FFI::isNull — FFI\CData が NULL ポインターかどうかを調べる
- FFI::load — C のヘッダーファイルから C の宣言を読み込む
- FFI::memcmp — メモリ領域を比較する
- FFI::memcpy — あるメモリ領域を別の領域へコピーする
- FFI::memset — メモリ領域を埋める
- FFI::new — C のデータ構造を作成する
- FFI::scope — 事前ロード中にパースされた C の宣言を使って FFI オブジェクトをインスタンス化する
- FFI::sizeof — C のデータサイズまたは C の型サイズを取得する
- FFI::string — メモリ領域から PHP の文字列を作成する
- FFI::type — C の宣言から FFI\CType オブジェクトを作成する
- FFI::typeof — FFI\CData の FFI\CType を取得する

# C のデータハンドル

(PHP 7 >= 7.4.0, PHP 8)

## はじめに

FFI\CData オブジェクトは、通常の PHP データのように様々な方法で使用できます:

- スカラー型の C のデータは $cdata プロパティを通してアクセスできます。例: `$x = FFI::new('int'); $x->cdata = 42;`
- C の構造体や共用体のフィールドは通常の PHP のオブジェクトプロパティのようにアクセスできます。例: `$cdata->field`
- C の配列要素は通常の PHP の配列要素のようにアクセスできます。例: `$cdata[$offset]`
- C の配列は `foreach` 文を使って反復できます。
- C の配列は count() の引数として使えます。
- C のポインタは配列のように参照外しできます。例: `$cdata[0]`
- C のポインタは通常の比較演算子を使って比較できます (`<`、 `<=`、`==`、`!=`、`>=`、`>`)。
- C のポインタは通常の `+`/`-`/ `++`/`--` 演算子を使ってインクリメント・デクリメントできます。例: `$cdata += 5`
- C のポインタは通常の `-` 演算子を使って他のポインタと引き算できます。
- C の関数ポインタは通常の PHP のクロージャのように呼び出せます。例: `$cdata()`
- 任意の C のデータは clone 演算子を使って 複製できます。例: `$cdata2 = clone $cdata;`
- 任意の C のデータは var_dump() や print_r() 等を 使って可視化できます。
- PHP 8.3.0 以降、FFI\CData は構造体やフィールドに代入できるようになりました。

> 注意: 特筆すべき制限として、FFI\CData インスタンスは isset()、empty()、unset() をサポートしていません。 また、ラップされた C の構造体や共用体は Traversable を実装していません。

## クラス概要

namespace FFI;
final class CData {
}

## 変更履歴

バージョン | 説明
--- | ---
8.3.0 | FFI\CData は構造体やフィールドに代入できるようになりました。

# C の型ハンドル

(PHP 7 >= 7.4.0, PHP 8)

## はじめに

## クラス概要

namespace FFI;
final class 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 function getAlignment(): int
public function getArrayElementType(): FFI\CType
public function getArrayLength(): int
public function getAttributes(): int
public function getEnumKind(): int
public function getFuncABI(): int
public function getFuncParameterCount(): int
public function getFuncParameterType(int `$index`): FFI\CType
public function getFuncReturnType(): FFI\CType
public function getKind(): int
public function getName(): string
public function getPointerType(): FFI\CType
public function getSize(): int
public function getStructFieldNames(): array
public function getStructFieldOffset(string `$name`): int
public function 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

(PHP 8 >= 8.1.0)

FFI\CType::getAlignment — 説明

### 説明

public function FFI\CType::getAlignment(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# FFI\CType::getArrayElementType

(PHP 8 >= 8.1.0)

FFI\CType::getArrayElementType — 説明

### 説明

public function FFI\CType::getArrayElementType(): FFI\CType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# FFI\CType::getArrayLength

(PHP 8 >= 8.1.0)

FFI\CType::getArrayLength — 説明

### 説明

public function FFI\CType::getArrayLength(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# FFI\CType::getAttributes

(PHP 8 >= 8.1.0)

FFI\CType::getAttributes — 説明

### 説明

public function FFI\CType::getAttributes(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# FFI\CType::getEnumKind

(PHP 8 >= 8.1.0)

FFI\CType::getEnumKind — 説明

### 説明

public function FFI\CType::getEnumKind(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# FFI\CType::getFuncABI

(PHP 8 >= 8.1.0)

FFI\CType::getFuncABI — 説明

### 説明

public function FFI\CType::getFuncABI(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# FFI\CType::getFuncParameterCount

(PHP 8 >= 8.1.0)

FFI\CType::getFuncParameterCount — 関数型の引数の数を取得する

### 説明

public function FFI\CType::getFuncParameterCount(): int

### パラメータ

この関数にはパラメータはありません。

### 戻り値

内部的に保持している関数型の引数の数を返します。 内部的に保持している型が関数でない場合、 FFI\Exception をスローします。

# FFI\CType::getFuncParameterType

(PHP 8 >= 8.1.0)

FFI\CType::getFuncParameterType — 関数の引数の型を取得する

### 説明

public function FFI\CType::getFuncParameterType(int `$index`): FFI\CType

内部的に保持している関数型の引数の型を返します。

### パラメータ

`index`
  関数の引数の添字 (ゼロ始まり)。

### 戻り値

内部的に保持している関数型の引数の型を返します。 内部的に保持している型が関数でない場合や、 与えられた添字がその関数の引数の範囲外の場合、 FFI\Exception をスローします。

# FFI\CType::getFuncReturnType

(PHP 8 >= 8.1.0)

FFI\CType::getFuncReturnType — 説明

### 説明

public function FFI\CType::getFuncReturnType(): FFI\CType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# FFI\CType::getKind

(PHP 8 >= 8.1.0)

FFI\CType::getKind — 説明

### 説明

public function FFI\CType::getKind(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# FFI\CType::getName

(PHP 7 >= 7.4.0, PHP 8)

FFI\CType::getName — 説明

### 説明

public function FFI\CType::getName(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# FFI\CType::getPointerType

(PHP 8 >= 8.1.0)

FFI\CType::getPointerType — 説明

### 説明

public function FFI\CType::getPointerType(): FFI\CType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# FFI\CType::getSize

(PHP 8 >= 8.1.0)

FFI\CType::getSize — 説明

### 説明

public function FFI\CType::getSize(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# FFI\CType::getStructFieldNames

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldNames — 説明

### 説明

public function FFI\CType::getStructFieldNames(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# FFI\CType::getStructFieldOffset

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldOffset — 説明

### 説明

public function FFI\CType::getStructFieldOffset(string `$name`): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`name`

### 戻り値

# FFI\CType::getStructFieldType

(PHP 8 >= 8.1.0)

FFI\CType::getStructFieldType — 説明

### 説明

public function FFI\CType::getStructFieldType(string `$name`): FFI\CType

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`name`

### 戻り値

## 目次

- FFI\CType::getAlignment — 説明
- FFI\CType::getArrayElementType — 説明
- FFI\CType::getArrayLength — 説明
- FFI\CType::getAttributes — 説明
- FFI\CType::getEnumKind — 説明
- FFI\CType::getFuncABI — 説明
- FFI\CType::getFuncParameterCount — 関数型の引数の数を取得する
- FFI\CType::getFuncParameterType — 関数の引数の型を取得する
- FFI\CType::getFuncReturnType — 説明
- FFI\CType::getKind — 説明
- FFI\CType::getName — 説明
- FFI\CType::getPointerType — 説明
- FFI\CType::getSize — 説明
- FFI\CType::getStructFieldNames — 説明
- FFI\CType::getStructFieldOffset — 説明
- FFI\CType::getStructFieldType — 説明

# FFI 例外

(PHP 7 >= 7.4.0, PHP 8)

## はじめに

## クラス概要

namespace FFI;
class 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 function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

# FFI パーサー例外

(PHP 7 >= 7.4.0, PHP 8)

## はじめに

## クラス概要

namespace FFI;
final class 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 function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function Error::__clone(): void
}

- インストール/設定
  - 要件
  - インストール手順
  - 実行時設定
- 例
  - FFI の基本的な使い方
  - PHP のコールバック
  - PHP/FFI/事前ロードの完全な例
- FFI — C のコードやデータへの主要インターフェース
  - FFI::addr — C のデータへのアンマネージドなポインターを作成する
  - FFI::alignof — アラインメントを取得する
  - FFI::arrayType — 新しい C の配列型を動的に構築する
  - FFI::cast — C の型キャストを実行する
  - FFI::cdef — 新しい FFI オブジェクトを作成する
  - FFI::free — アンマネージドなデータ構造を解放する
  - FFI::isNull — FFI\CData が NULL ポインターかどうかを調べる
  - FFI::load — C のヘッダーファイルから C の宣言を読み込む
  - FFI::memcmp — メモリ領域を比較する
  - FFI::memcpy — あるメモリ領域を別の領域へコピーする
  - FFI::memset — メモリ領域を埋める
  - FFI::new — C のデータ構造を作成する
  - FFI::scope — 事前ロード中にパースされた C の宣言を使って FFI オブジェクトをインスタンス化する
  - FFI::sizeof — C のデータサイズまたは C の型サイズを取得する
  - FFI::string — メモリ領域から PHP の文字列を作成する
  - FFI::type — C の宣言から FFI\CType オブジェクトを作成する
  - FFI::typeof — FFI\CData の FFI\CType を取得する
- FFI\CData — C のデータハンドル
- FFI\CType — C の型ハンドル
  - FFI\CType::getAlignment — 説明
  - FFI\CType::getArrayElementType — 説明
  - FFI\CType::getArrayLength — 説明
  - FFI\CType::getAttributes — 説明
  - FFI\CType::getEnumKind — 説明
  - FFI\CType::getFuncABI — 説明
  - FFI\CType::getFuncParameterCount — 関数型の引数の数を取得する
  - FFI\CType::getFuncParameterType — 関数の引数の型を取得する
  - FFI\CType::getFuncReturnType — 説明
  - FFI\CType::getKind — 説明
  - FFI\CType::getName — 説明
  - FFI\CType::getPointerType — 説明
  - FFI\CType::getSize — 説明
  - FFI\CType::getStructFieldNames — 説明
  - FFI\CType::getStructFieldOffset — 説明
  - FFI\CType::getStructFieldType — 説明
- FFI\Exception — FFI 例外
- FFI\ParserException — FFI パーサー例外

# OPcache

# はじめに

OPcache はコンパイル済みのバイトコードを共有メモリに保存し、PHP がリクエストのたびにスクリプトを読み込み、パースする手間を省くことでパフォーマンスを向上させます。

このPHP拡張モジュールは PHP 5.5.0 以降のバージョンにバンドルされています。 PHP 5.2, 5.3, 5.4 では » PECL で利用可能です。

# インストール/設定

## 目次

- インストール手順
- 実行時設定

## インストール手順

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 | "disable" | `INI_ALL` | PHP 8.0.0 以降で利用可能。PHP 8.4.0 より前のバージョンでは、デフォルト値は "tracing" でした。
opcache.jit_buffer_size | 64M | `INI_SYSTEM` | PHP 8.0.0 以降で利用可能。PHP 8.4.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 | 61 | `INI_SYSTEM` | PHP 8.0.0 以降で利用可能。PHP 8.5.0 より前のバージョンでは、デフォルト値は 64 でした。
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 単位） 最大値は、64bit アーキテクチャでは 32767 であり、 32bit アーキテクチャでは 4095 です。

  > 注意: PHP 8.4.0 より前のバージョンの最大値は、 すべてのアーキテクチャで 4095 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
  どの最適化パスが実行されるかコントロールするビットマスク。 デフォルト値は `0x7FFEBFFF` で、すべての安全な最適化が有効になっています。 最適化を無効にしたり、安全でない最適化を有効にするのが役に立つのは、 大半が最適化エンジンをデバッグ/開発する時です。 ビットマスクの各ビットが、特定の最適化パスを有効にします:

  最適化パスのビットマスク
  ビット | パス名 | 説明 | デフォルト
  --- | --- | --- | ---
  0 | PASS_1 | 単純なピープホール最適化 | 有効
  1 | PASS_2 | 未使用 (PASS_1 に統合済み) | 有効
  2 | PASS_3 | 単純なジャンプ最適化 | 有効
  3 | PASS_4 | コール最適化 | 有効
  4 | PASS_5 | 制御フローグラフに基づく最適化 | 有効
  5 | PASS_6 | データフロー解析に基づく最適化 | 有効
  6 | PASS_7 | SSA ベースの最適化にコールグラフを使用するかどうか | 有効
  7 | PASS_8 | 疎条件定数伝播 | 有効
  8 | PASS_9 | 一時変数の最適化 | 有効
  9 | PASS_10 | NOP オペコードの除去 | 有効
  10 | PASS_11 | リテラルの圧縮 | 有効
  11 | PASS_12 | コールスタックサイズの事前計算 | 有効
  12 | PASS_13 | 未使用変数の除去 | 有効
  13 | PASS_14 | デッドコードの除去 | 有効
  14 | PASS_15 | 定数宣言の収集と置換 (安全でない) | 無効
  15 | PASS_16 | 自明な関数のインライン化 (コール最適化の一部) | 有効
  16 | (フラグ) | 演算子オーバーロードの可能性を無視する (安全でない) | 無効

  > 注意: 安全な最適化と安全でない最適化
  > 安全な最適化 (デフォルトで有効) は、 PHP コードの正確な動作を維持しつつパフォーマンスを向上させます。 デッドコードの除去、定数畳み込み、ジャンプ最適化がこれに含まれます。 安全でない最適化 (デフォルトで無効) は、 エッジケースで動作を変える可能性があります:

  > - ビット 14: 定数の収集。定数がコンパイル時に置換され、 実行時の宣言順序が無視されます:

  >       <?php
  >       echo getA();         // Error をスローする代わりに "hello" を出力
  >       const A = "hello";
  >       function getA() { return A; }

  > - ビット 16: 演算子オーバーロードを無視。 `do_operation` を持つクラス (例: GMP、 BCMath) を 算術演算で使用している場合に安全ではありません。 型宣言を使用することで、最適化エンジンは同じ最適化を安全に適用できます。

`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` を指定した場合は許可されます。 PHP 8.3.0 以降では、CLI SAPI や phpdbg SAPI から 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 5 >= 5.5.5, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_compile_file — PHP スクリプトを、実行せずにコンパイルしてキャッシュする

### 説明

function opcache_compile_file(string `$filename`): bool

この関数は、PHP スクリプトをコンパイルして opcode キャッシュに追加しますが、スクリプトは実行しません。 これを使うと、ウェブサーバーの再起動後にファイルをキャッシュしておき、 後でリクエストがあったときにそのキャッシュを使えるようになります。

### パラメータ

`filename`
  コンパイルしたい PHP スクリプトへのパス。

### 戻り値

`filename` を正常にコンパイルしたときに `true` を返します。 失敗した場合に `false` を返します。

### エラー / 例外

`filename` を読み込めなかったりコンパイルできなかったりした場合は `E_WARNING` レベルのエラーが発生します。 @ を使えば、この警告を抑制できます。

### 参考

- opcache_invalidate() - キャッシュされたスクリプトを無効にする

# opcache_get_configuration

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_get_configuration — キャッシュについての構成情報を取得

### 説明

function opcache_get_configuration(): array|false

この関数は、キャッシュ・インスタンスについての構成情報を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

情報の配列を返します。その配列は ini 、ブラックリストおよびバージョンを含みます。

### エラー / 例外

`opcache.restrict_api` を使用中で、 かつ現在のパスがルール違反の場合、 E_WARNING が発生します。 ステータス情報は返されません。

### 参考

- opcache_get_status() - キャッシュについてのステータス情報を取得

# opcache_get_status

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache > 7.0.2)

opcache_get_status — キャッシュについてのステータス情報を取得

### 説明

function opcache_get_status(bool `$include_scripts` = `true`): array|false

この関数は、インメモリ の キャッシュ・インスタンス についてのステータス情報を返します。 ファイルキャッシュに関する情報は一切返しません。

### パラメータ

`include_scripts`
  スクリプト固有の状態の情報を含む。

### 戻り値

情報の配列を返します。スクリプト固有の状態の情報をオプションで含みます、 失敗した場合に `false` を返します。

### エラー / 例外

`opcache.restrict_api` を使用中で、 かつ現在のパスがルール違反の場合、 E_WARNING が発生します。 ステータス情報は返されません。

### 変更履歴

バージョン | 説明
--- | ---
PHP 8.3.0 | `opcache_get_status()['scripts'][n]['revalidate']` の値に、 いつスクリプトの更新チェックを行うかの予定が Unix タイムスタンプの形で含まれるようになりました。 いつチェックを行うかは、INI ディレクティブ opcache.revalidate_freq によって決まります。

### 例

例1 opcache_get_status() の例

    <?php
    var_dump(opcache_get_status());
    ?>

上の例の出力は、 たとえば以下のようになります。

    array(9) {
      'opcache_enabled' =>
      bool(true)
      'cache_full' =>
      bool(false)
      'restart_pending' =>
      bool(false)
      'restart_in_progress' =>
      bool(false)
      'memory_usage' =>
      array(4) {
        'used_memory' =>
        int(9167936)
        'free_memory' =>
        int(125049792)
        'wasted_memory' =>
        int(0)
        'current_wasted_percentage' =>
        double(0)
      }
      'interned_strings_usage' =>
      array(4) {
        'buffer_size' =>
        int(8388608)
        'used_memory' =>
        int(2593616)
        'free_memory' =>
        int(5794992)
        'number_of_strings' =>
        int(10358)
      }
      'opcache_statistics' =>
      array(13) {
        'num_cached_scripts' =>
        int(0)
        'num_cached_keys' =>
        int(0)
        'max_cached_keys' =>
        int(16229)
        'hits' =>
        int(0)
        'start_time' =>
        int(1733310010)
        'last_restart_time' =>
        int(0)
        'oom_restarts' =>
        int(0)
        'hash_restarts' =>
        int(0)
        'manual_restarts' =>
        int(0)
        'misses' =>
        int(0)
        'blacklist_misses' =>
        int(0)
        'blacklist_miss_ratio' =>
        double(0)
        'opcache_hit_rate' =>
        double(0)
      }
      'scripts' =>
      array(0) {
      }
      'jit' =>
      array(7) {
        'enabled' =>
        bool(false)
        'on' =>
        bool(false)
        'kind' =>
        int(5)
        'opt_level' =>
        int(4)
        'opt_flags' =>
        int(6)
        'buffer_size' =>
        int(0)
        'buffer_free' =>
        int(0)
      }
    }

### 参考

- opcache_get_configuration() - キャッシュについての構成情報を取得

# opcache_invalidate

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.0)

opcache_invalidate — キャッシュされたスクリプトを無効にする

### 説明

function 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_is_script_cached

(PHP 5 >= 5.5.11, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.4)

opcache_is_script_cached — スクリプトが OPCache にキャッシュされているかどうかを伝えます。

### 説明

function opcache_is_script_cached(string `$filename`): bool

この関数は、PHP スクリプトが OPCache にキャッシュされているかチェックします。 これは、特定のスクリプトに対するキャッシュの "ウォーミング" をより簡単に検出するために使用できます。 この関数は、インメモリキャッシュ の情報だけをチェックします。 ファイルキャッシュ の情報はチェックしません。 ファイルキャッシュをチェックするには、 opcache_is_script_cached_in_file_cache() を使います。

### パラメータ

`filename`
  チェックされる PHP スクリプトへのパスです。

### 戻り値

`filename` が OPCache のインメモリキャッシュにキャッシュされている場合、`true` を、 そうでなければ `false` を返します。

### 参考

- opcache_compile_file() - PHP スクリプトを、実行せずにコンパイルしてキャッシュする
- opcache_is_script_cached_in_file_cache() - スクリプトが OPCache のファイルキャッシュにキャッシュされているかどうかを伝えます

# opcache_is_script_cached_in_file_cache

(PHP 8 >= 8.5.0)

opcache_is_script_cached_in_file_cache — スクリプトが OPCache のファイルキャッシュにキャッシュされているかどうかを伝えます

### 説明

function opcache_is_script_cached_in_file_cache(string `$filename`): bool

この関数は、PHP スクリプトが OPCache にキャッシュされているかチェックします。 これは、特定のスクリプトに対するキャッシュの "ウォーミング" をより簡単に検出するために使用できます。 この関数は、ファイルキャッシュの情報だけをチェックし、インメモリキャッシュはチェックしません。 インメモリキャッシュをチェックするには、opcache_is_script_cached() を使用してください。

### パラメータ

`filename`
  チェックされる PHP スクリプトへのパスです。

### 戻り値

`filename` が OPCache にキャッシュされている場合、`true` を、 そうでなければ `false` を返します。

### 参考

- opcache_compile_file() - PHP スクリプトを、実行せずにコンパイルしてキャッシュする
- opcache_is_script_cached() - スクリプトが OPCache にキャッシュされているかどうかを伝えます。

# opcache_jit_blacklist

(PHP 8 >= 8.4.0)

opcache_jit_blacklist — 関数を JIT コンパイルのブラックリストに追加する

### 説明

function opcache_jit_blacklist( Closure `$closure` ): void

Tracing JIT が使用されている場合に、特定の関数を JIT コンパイルのブラックリストに追加します。 対象の関数は Closure を使って指定します。

警告

既に JIT コンパイルされた部分は影響を受けず、 引き続き JIT コンパイルされたままになります。

### パラメータ

`closure`
  ブラックリストに追加する関数。第一級callable (first class callable) として表現されます。 無名関数を渡すこともでき、その場合は無名関数自体がブラックリストに追加されます。

### 戻り値

値を返しません。

### 例

例1 opcache_jit_blacklist() の基本的な例

    <?php
    function foo() {
        $x = 1;
        $x += 0;
        ++$x;
        var_dump($x);
    }
    opcache_jit_blacklist(foo(...));
    foo();
    ?>

### 参考

- opcache_invalidate() - キャッシュされたスクリプトを無効にする
- opcache_reset() - opcode のキャッシュ内容をリセットする

# opcache_reset

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL ZendOpcache >= 7.0.0)

opcache_reset — opcode のキャッシュ内容をリセットする

### 説明

function 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() - キャッシュについてのステータス情報を取得

## 目次

- opcache_compile_file — PHP スクリプトを、実行せずにコンパイルしてキャッシュする
- opcache_get_configuration — キャッシュについての構成情報を取得
- opcache_get_status — キャッシュについてのステータス情報を取得
- opcache_invalidate — キャッシュされたスクリプトを無効にする
- opcache_is_script_cached — スクリプトが OPCache にキャッシュされているかどうかを伝えます。
- opcache_is_script_cached_in_file_cache — スクリプトが OPCache のファイルキャッシュにキャッシュされているかどうかを伝えます
- opcache_jit_blacklist — 関数を JIT コンパイルのブラックリストに追加する
- opcache_reset — opcode のキャッシュ内容をリセットする

- インストール/設定
  - インストール手順
  - 実行時設定
- コードの事前ロード
- OPcache 関数
  - opcache_compile_file — PHP スクリプトを、実行せずにコンパイルしてキャッシュする
  - opcache_get_configuration — キャッシュについての構成情報を取得
  - opcache_get_status — キャッシュについてのステータス情報を取得
  - opcache_invalidate — キャッシュされたスクリプトを無効にする
  - opcache_is_script_cached — スクリプトが OPCache にキャッシュされているかどうかを伝えます。
  - opcache_is_script_cached_in_file_cache — スクリプトが OPCache のファイルキャッシュにキャッシュされているかどうかを伝えます
  - opcache_jit_blacklist — 関数を JIT コンパイルのブラックリストに追加する
  - opcache_reset — opcode のキャッシュ内容をリセットする

# 出力バッファリング制御

# はじめに

出力制御関数により、スクリプトから送信される出力を制御することが可 能になります。この機能は、複数の異なった場面、特にスクリプトがデー タ出力を開始した後にヘッダをブラウザに送信する必要がある場合に有用 です。出力制御関数は、header() または setcookie()を使用して送信されたヘッダには作用せ ず、echo のような関数とPHPコードのブロック間 のデータにのみ作用します。

# インストール/設定

## 目次

- 実行時設定

## 実行時設定

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 を指定するために使われていました。

`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 8.4.0 より前のバージョンでは、 出力バッファを開始するときにもこのフラグを設定できました。

`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 のユーザレベル出力バッファは、 起動した後から、バッファリングをオフにするか、 スクリプトが終わるまでのすべての出力をバッファリングします。 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() を使ってヘッダを送信する場合です。

## 出力バッファをオンにする

出力バッファリングは、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_*` 関数は、アクティブな出力バッファ（最後に開始されたもの）に対してのみ動作するため、 アクティブなバッファのみをフラッシュ、クリーン、オフにすることができます。 それ以外のバッファに対して動作する関数は、 使用中のすべての出力ハンドラのリストを返す 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つの操作を実行できます。

## バッファの内容をフラッシュ/アクセス/削除する

フラッシュは、アクティブなバッファの内容を送信し、破棄します。 出力バッファは、出力のサイズがバッファのサイズを超えたときか、 スクリプトが終了するか、 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 のシャットダウン処理によってフラッシュされ、オフになります。 バッファは、起動した順序と逆の順序でフラッシュされ、オフになります。 最後にバッファリングが開始されたものが最初になり、 最初にバッファリングが開始されたものが最後にフラッシュされ、オフになります。

警告

バッファの内容をフラッシュしたくない場合は、 カスタムの出力ハンドラを使い、シャットダウン中のフラッシュを防ぐべきです。

## 出力ハンドラ

出力ハンドラは、出力バッファに関連付けられた 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() です。

## 出力ハンドラを扱う

出力ハンドラが呼び出されると、 バッファの内容と、出力バッファリングの状態を示すビットマスクが渡されます。

function 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() ob_clean(), ob_flush() をコールしてもハンドラは呼び出されません。 PHP のシャットダウン処理中でも同様です。 PHP 8.4.0 より前のバージョンでは、 ob_clean() をコールしてもこのフラグは何の効果もありませんでした。

> 注意: 一部のウェブサーバー、例えば 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` フラグが設定されます。

## 出力ハンドラでスローされる例外

捕捉されない例外が出力ハンドラでスローされた場合、 プログラムは終了し、`"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() ob_clean(), ob_flush() 経由でハンドラは呼び出されません。 PHP のシャットダウン処理中でも同様です。 PHP 8.4.0 より前のバージョンでは、 ob_clean() や ob_flush() をコールしてもこのフラグはなんの意味もありませんでした。

# 例

## 目次

- 基本的な使用法
- 出力リライトの使用法

## 基本的な使用法

例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

(PHP 4, PHP 5, PHP 7, PHP 8)

flush — システム出力バッファをフラッシュする

### 説明

function flush(): void

PHP および PHP が使っている (CGI, Web サーバーなどの) バックエンドのシステム書き込みバッファをフラッシュします。 コマンドライン環境では、flush() はバッファの中身だけをフラッシュしようとします。 一方で web のコンテキストではヘッダとバッファの内容をフラッシュします。

> 注意: flush() はウェブサーバーのバッファリング手法を上書きすることはできません。 また、クライアント側のブラウザでのバッファリングにはなんの影響も及ぼしません。

> 注意: この関数は、 ob_start() や output_add_rewrite_var() によって開始されたユーザーレベルの出力ハンドラには、何ら影響しません。

警告

flush() は、 ハンドラがヘッダを送信する前にヘッダを送信することで、 web のコンテキストでヘッダを設定したり送信したりするハンドラ (例:ob_gzhandler()) を中断させることができます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

値を返しません。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | FastCGI 利用時に、本文なしでヘッダをフラッシュできるようになりました。

### 参考

- ob_flush() - アクティブな出力ハンドラの戻り値をフラッシュ(送信)する
- ob_clean() - アクティブな出力バッファの内容をクリア(消去)する
- ob_end_flush() - アクティブな出力用バッファをフラッシュ(送信)し、アクティブな出力バッファをオフにする
- ob_end_clean() - アクティブな出力用バッファをクリア(消去)し、出力のバッファリングをオフにする

# ob_clean

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_clean — アクティブな出力バッファの内容をクリア(消去)する

### 説明

function 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_end_clean

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_end_clean — アクティブな出力用バッファをクリア(消去)し、出力のバッファリングをオフにする

### 説明

function ob_end_clean(): bool

この関数は、 (`PHP_OUTPUT_HANDLER_CLEAN` と `PHP_OUTPUT_HANDLER_FINAL` フラグを指定して) 出力ハンドラをコールし、その戻り値を破棄するとともに、 アクティブな出力バッファの内容をクリア(消去)し、 かつそれをオフにします。

`PHP_OUTPUT_HANDLER_REMOVABLE` を指定して アクティブな出力バッファを開始しないと、 ob_end_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_flush

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_end_flush — アクティブな出力用バッファをフラッシュ(送信)し、アクティブな出力バッファをオフにする

### 説明

function 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_flush

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_flush — アクティブな出力ハンドラの戻り値をフラッシュ(送信)する

### 説明

function 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_get_clean

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_get_clean — アクティブな出力バッファの内容を取得し、そのバッファをオフにする

### 説明

function 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_contents

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_get_contents — 出力用バッファの内容を返す

### 説明

function 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_flush

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_get_flush — アクティブな出力ハンドラの戻り値をフラッシュ(送信)し、その内容を文字列として返した後で、それをオフにする

### 説明

function 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_length

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

ob_get_length — 出力バッファの長さを返す

### 説明

function 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_level

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_get_level — 出力バッファリング機構のネストレベルを返す

### 説明

function 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_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ob_get_status — 出力バッファのステータスを取得する

### 説明

function 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_implicit_flush

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_implicit_flush — 自動フラッシュをオンまたはオフにする

### 説明

function 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_list_handlers

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

ob_list_handlers — 使用中の出力ハンドラの一覧を取得する

### 説明

function 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_start

(PHP 4, PHP 5, PHP 7, PHP 8)

ob_start — 出力のバッファリングを有効にする

### 説明

function 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` を返します。 コールバックのシグネチャは、次のとおりです。

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

  > 注意: PHP 8.4.0 より前のバージョンでは、flags パラメータに 出力ハンドラのステータスフラグ も指定可能でした。

### 戻り値

成功した場合に `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 コールバック関数

# output_add_rewrite_var

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

output_add_rewrite_var — URL リライタの値を追加する

### 説明

function 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'` ハンドラがオフにされると、 再び値を保存することはできません。

警告

PHP 8.4.0より前では、書き換えられるホストは url_rewriter.hosts ではなく session.trans_sid_hosts で設定されていました。

### パラメータ

`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

# output_reset_rewrite_vars

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

output_reset_rewrite_vars — URL リライタの値をリセットする

### 説明

function 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

## 目次

- 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 リライタの値をリセットする

- インストール/設定
  - 実行時設定
- 定義済み定数
- 出力バッファリング
- システムバッファのフラッシュ
- ユーザーレベルの出力バッファ
  - どの出力をバッファするのか？
  - 出力バッファをネストさせる
  - バッファサイズ
  - バッファに対して可能な操作
  - 出力ハンドラ
  - 出力ハンドラを扱う
  - 出力ハンドラに渡されるフラグ
  - 出力ハンドラの戻り値
- 例
  - 基本的な使用法
  - 出力リライトの使用法
- 出力制御 関数
  - 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 リライタの値をリセットする

# PHP オプションと情報

# はじめに

以下の関数によりPHP自体に関する多くの情報(例えば、実行時の設定、 ロードされている拡張モジュール、バージョン等)を 得ることができます。実行しているPHPのオプションを設定する関数もあ ります。おそらく最も有名な関数であるphpinfo() もここにあります。

# インストール/設定

## 目次

- 実行時設定

## 実行時設定

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` |
zend.max_allowed_stack_size | "0" | `INI_SYSTEM` | PHP 8.3.0 以降で利用可能
zend.reserved_stack_size | "0" | `INI_SYSTEM` | PHP 8.3.0 以降で利用可能
fiber.stack_size |  | `INI_ALL` | PHP 8.1.0 以降で利用可能

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

  循環参照コレクタを有効あるいは無効にします。

`zend.max_allowed_stack_size` int

  オペレーティングシステムが、 プログラムに使うことを許可しているネイティブスタックスペースの最大値。 オペレーティングシステムが許可している以上のサイズを使おうとすると、 通常はハードなクラッシュが発生し、 デバッグ情報が簡単に利用できることはありません。 デバッグを容易にするために、PHP のエンジンはそうしたことが発生する前に (zend.max_allowed_stack_size-zend.reserved_stack_size バイト以上のスタックをプログラムが使った場合に) Error をスローします。

  ユーザー定義の再帰的なコードは、ネイティブスタック空間を消費しません。 しかし、内部関数やマジックメソッドは消費します。 これらの関数を含む、とても深い再帰コードは、 利用可能なネイティブスタックスペースをすべて使い切る原因になりえます。

  この このパラメータに設定可能な値は下記の通りです:

  - `0`: プログラムが消費できる、 オペレーティングシステムのネイティブスタックスペースの最大値を自動検知します。これがデフォルトです。 検知できない場合は、既知のシステムのデフォルト値を使います。
  - `-1`: エンジンのスタックサイズチェックを無効にします。
  - 正の整数: 固定のサイズをバイト単位で指定します。 この値に大き過ぎる値を指定すると、スタックサイズチェックを無効にすることと同じことになります。

  fibers のスタックサイズは fiber.stack_size によって決まります。 Fiber の実行中に行われるスタックをチェックする際には、 zend.max_allowed_stack_size の代わりにこれを使います。

  > 注意:

  > この機能は スタック バッファ のオーバーフローとは無関係です。つまり、セキュリティ機能ではありません。

`zend.reserved_stack_size` int

  予約するスタックのサイズを、バイト単位で指定します。 この値はバッファの値として スタックサイズをチェックする際に max allowed stack size から引かれます。

  このパラメータに設定可能な値は下記の通りです:

  - `0`: 適切な値を自動的に検知します。
  - 正の整数: 固定のサイズをバイト単位で指定します。
`fiber.stack_size` int

  個別の Fiber に割り当てられるネイティブスタックサイズを、 バイト単位で指定します。

  ポインタのサイズが8バイトより小さいシステムでは、 デフォルト値は 1MiB です。 8バイト以上のシステムでは、デフォルトは 2MiB です。

# 定義済み定数

以下の定数は、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) | アサーションに失敗するたびに AssertionError をスローします。 警告 この機能は 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

(PHP 4, PHP 5, PHP 7, PHP 8)

assert — アサーションの値を調べる

### 説明

function 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` | アサーションが失敗した時にコールされるユーザー定義の関数。 シグネチャは以下の形であるべきです: function assert_callback( string `$file`, int `$line`, null `$assertion`, string `$description` = ? ): void | PHP 8.0.0 より前のバージョンでは、 コールバックのシグネチャは以下の形であるべきでした: function 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.active=0`
- `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_options

(PHP 4, PHP 5, PHP 7, PHP 8)

assert_options — 様々な assert フラグを設定/取得する

警告

この関数は PHP 8.3.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

function 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 に設定するコールバック関数は、次のようなシグネチャを持つべきです:

  function 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_options() は、推奨されなくなりました。
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() - アサーションの値を調べる

# cli_get_process_title

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

cli_get_process_title — 現在のプロセスのタイトルを返す

### 説明

function 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_set_process_title

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

cli_set_process_title — プロセスのタイトルを設定する

### 説明

function cli_set_process_title(string `$title`): bool

プロセスのタイトルを設定します。これは top や ps といったツールで表示されます。 この関数は、 CLI モードでしか使えません。

### パラメータ

`title`
  新しいタイトル。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### エラー / 例外

OS がこの機能に対応していない場合に `E_WARNING` が発生します。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | 長すぎるプロセスのタイトルを設定しようとすると、 cli_set_process_title() は `E_WARNING` を発生させるようになりました。 以前は、タイトルは切り詰められていました。

### 例

    <?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() - 現在のプロセスのタイトルを返す

# dl

(PHP 4, PHP 5, PHP 7, PHP 8)

dl — 実行時に PHP 拡張モジュールをロードする

### 説明

function 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() - ある拡張モジュールがロードされているかどうかを調べる

# extension_loaded

(PHP 4, PHP 5, PHP 7, PHP 8)

extension_loaded — ある拡張モジュールがロードされているかどうかを調べる

### 説明

function 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 を返す

# gc_collect_cycles

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_collect_cycles — すべての既存ガベージサイクルを強制的に収集する

### 説明

function gc_collect_cycles(): int

すべての既存ガベージサイクルを強制的に収集します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

収集したサイクルの数を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | 戻り値に、サイクルを通じて間接的に収集された文字列とリソースが 含まれなくなりました。

### 参考

- ガベージコレクション

# gc_disable

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_disable — 循環参照コレクタを無効にする

### 説明

function gc_disable(): void

zend.enable_gc を `0` に設定して、循環参照コレクタを無効にします。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

値を返しません。

### 参考

- ガベージコレクション

# gc_enable

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_enable — 循環参照コレクタを有効にする

### 説明

function gc_enable(): void

zend.enable_gc を `1` に設定して、循環参照コレクタを有効にします。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

値を返しません。

### 参考

- ガベージコレクション

# gc_enabled

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gc_enabled — 循環参照コレクタの状態を返す

### 説明

function gc_enabled(): bool

循環参照コレクタの状態を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

ガベージコレクタが有効な場合に `true`、そうでない場合に `false` を返します。

### 例

例1 gc_enabled() の例

    <?php
    if(gc_enabled()) gc_collect_cycles();
    ?>

### 参考

- ガベージコレクション

# gc_mem_caches

(PHP 7, PHP 8)

gc_mem_caches — Zend Engine のメモリーマネージャによって使用されたメモリーを再利用する

### 説明

function gc_mem_caches(): int

Zend Engine のメモリーマネージャによって使用されたメモリーを再利用します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

解放されたバイト数を返します。

### 参考

- ガベージコレクション

# gc_status

(PHP 7 >= 7.3.0, PHP 8)

gc_status — ガベージコレクタに関する情報を取得する

### 説明

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

### 参考

- ガベージコレクション

# get_cfg_var

(PHP 4, PHP 5, PHP 7, PHP 8)

get_cfg_var — PHP 設定オプションの値を取得する

### 説明

function get_cfg_var(string `$option`): string|array|false

PHP の設定オプション `option` の値を取得します。

この関数は、 PHP がコンパイルされた際にセットされた設定情報や Apache の設定ファイルから読んだ設定情報は返しません。

システムが 設定ファイル を使用しているかどうかを確認するには、cfg_file_path の設定値を取得してみてください。 この値が利用可能なら、設定ファイルが使用されています。

### パラメータ

`option`

  設定オプションの名前。

### 戻り値

`option` で指定された PHP 設定オプションの現在の値を返し、 エラーの場合は `false` を返します。

### 参考

- ini_get() - 設定オプションの値を得る
- ini_get_all() - すべての設定オプションを得る

# get_current_user

(PHP 4, PHP 5, PHP 7, PHP 8)

get_current_user — 現在の PHP スクリプトの所有者の名前を取得する

### 説明

function 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_defined_constants

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

get_defined_constants — すべての定数の名前とその値を連想配列として返す

### 説明

function 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_extension_funcs

(PHP 4, PHP 5, PHP 7, PHP 8)

get_extension_funcs — あるモジュールの関数名を配列として返す

### 説明

function 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() - 拡張モジュールの関数を取得する

# get_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

get_include_path — 現在の include_path 設定オプションを取得する

### 説明

function 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

# get_included_files

(PHP 4, PHP 5, PHP 7, PHP 8)

get_included_files — include または require で読み込まれたファイルの名前を配列として返す

### 説明

function 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_loaded_extensions

(PHP 4, PHP 5, PHP 7, PHP 8)

get_loaded_extensions — コンパイル/ロードされている全てのモジュールの名前を配列として返す

### 説明

function 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 の設定情報を出力する

# 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 で 削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function get_magic_quotes_gpc(): false

常に `false` を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

常に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | この関数は削除されました。
7.4.0 | この関数は推奨されなくなりました。

### 参考

- addslashes() - 文字列をスラッシュでクォートする
- stripslashes() - クォートされた文字列のクォート部分を取り除く
- get_magic_quotes_runtime() - magic_quotes_runtime の現在アクティブな設定値を取得する
- ini_get() - 設定オプションの値を得る

# 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 で 削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function get_magic_quotes_runtime(): false

常に `false` を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

常に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | この関数は削除されました。
7.4.0 | この関数は推奨されなくなりました。

### 参考

- get_magic_quotes_gpc() - magic_quotes_gpc の現在の設定を得る

# get_required_files

(PHP 4, PHP 5, PHP 7, PHP 8)

get_required_files — get_included_files() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 get_included_files().

# get_resources

(PHP 7, PHP 8)

get_resources — アクティブなリソースを返す

### 説明

function get_resources(?string `$type` = `null`): array

現在アクティブなすべての resource の配列を返します。 オプションでリソース型によってフィルタリングされます。

> 注意: この関数は、デバッグやテストの用途に使うものです。 本番環境で使う用途を想定していません。 特に、通常のやり方ではアクセスできないリソース (例: 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() - 全ての定義済の変数を配列で返す

# getenv

(PHP 4, PHP 5, PHP 7, PHP 8)

getenv — 環境変数の値をひとつ、または全て取得する

### 説明

function 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 変数を取得する
- スーパーグローバル

# getlastmod

(PHP 4, PHP 5, PHP 7, PHP 8)

getlastmod — 最終更新時刻を取得する

### 説明

function 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() - ファイルの更新時刻を取得する

# getmygid

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

getmygid — PHP スクリプトの所有者の GID を得る

### 説明

function getmygid(): int|false

現在のスクリプトのグループ ID を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

現在のスクリプトのグループ ID を返します。またはエラー時に `false` を返します。

### 参考

- getmyuid() - PHP スクリプト所有者のユーザー ID を取得する
- getmypid() - PHP のプロセス ID を取得する
- get_current_user() - 現在の PHP スクリプトの所有者の名前を取得する
- getmyinode() - 現在のスクリプトの inode を取得する
- getlastmod() - 最終更新時刻を取得する

# getmyinode

(PHP 4, PHP 5, PHP 7, PHP 8)

getmyinode — 現在のスクリプトの inode を取得する

### 説明

function getmyinode(): int|false

現在のスクリプトの inode を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

現在のスクリプトの inode を表す整数値、あるいはエラーの場合は `false` を返します。

### 参考

- getmygid() - PHP スクリプトの所有者の GID を得る
- getmyuid() - PHP スクリプト所有者のユーザー ID を取得する
- getmypid() - PHP のプロセス ID を取得する
- get_current_user() - 現在の PHP スクリプトの所有者の名前を取得する
- getlastmod() - 最終更新時刻を取得する

# getmypid

(PHP 4, PHP 5, PHP 7, PHP 8)

getmypid — PHP のプロセス ID を取得する

### 説明

function getmypid(): int|false

現在の PHP プロセスの ID を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

現在の PHP のプロセス ID を返し、エラーの場合は `false` を返します。

### 注意

警告

プロセス ID は一意ではなく、エントロピ源として優れたものではありません。 セキュリティが問題となる状況では、PID に頼らないようにしましょう。

### 参考

- getmygid() - PHP スクリプトの所有者の GID を得る
- getmyuid() - PHP スクリプト所有者のユーザー ID を取得する
- get_current_user() - 現在の PHP スクリプトの所有者の名前を取得する
- getmyinode() - 現在のスクリプトの inode を取得する
- getlastmod() - 最終更新時刻を取得する

# getmyuid

(PHP 4, PHP 5, PHP 7, PHP 8)

getmyuid — PHP スクリプト所有者のユーザー ID を取得する

### 説明

function getmyuid(): int|false

現在のスクリプトのユーザー ID を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

現在のスクリプトのユーザー ID を返し、エラーの場合は `false` を返します。

### 参考

- getmygid() - PHP スクリプトの所有者の GID を得る
- getmypid() - PHP のプロセス ID を取得する
- get_current_user() - 現在の PHP スクリプトの所有者の名前を取得する
- getmyinode() - 現在のスクリプトの inode を取得する
- getlastmod() - 最終更新時刻を取得する

# getopt

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

getopt — コマンドライン引数のリストからオプションを取得する

### 説明

function 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

# getrusage

(PHP 4, PHP 5, PHP 7, PHP 8)

getrusage — 現在のリソース使用状況を取得する

### 説明

function getrusage(int `$mode` = 0): array|false

この関数は、getrusage(2) へのインターフェイスです。 システムコールから返されたデータを含む連想配列を返します。

### パラメータ

`mode`

  `mode` が 1 の場合、getrusage は `RUSAGE_CHILDREN` を付けてコールされます。

### 戻り値

システムコールから返されたデータを含む連想配列を返します。 すべてのエントリは、記述されたフィールド名を用いてアクセス可能です。 失敗時に `false` を返します。

### 例

例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_alter

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_alter — ini_set() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 ini_set().

# ini_get

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_get — 設定オプションの値を得る

### 説明

function ini_get(string `$option`): string|false

成功時に、設定オプションの値を返します。

### パラメータ

`option`

  設定オプションの名前。

### 戻り値

成功した場合に設定オプションの値、 `null` 値の場合は空の文字列を返します。 その設定オプションが存在しない場合は `false` を返します。

### 例

例1 ini_get() の例

    <?php

    /*
    php.ini で以下のように設定されているものとします:

    display_errors = On
    opcache.enable_cli = Off
    post_max_size = 8M
    */

    echo 'display_errors = ' . ini_get('display_errors') . "\n";
    echo 'opcache.enable_cli = ' . (int) ini_get('opcache.enable_cli') . "\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'));

    ?>

上の例の出力は、 たとえば以下のようになります。

    display_errors = 1
    opcache.enable_cli = 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に格納されている値を そのままの形式で返します。整数表現に変換したりはしません。 これらの値に通常の算術的な関数を施すと予期しない結果になります。 短縮記法をバイトに変換する用途として、 ini_parse_quantity() が使えます。

> 注意:

> ini_get() は、"配列" 形式の ini オプション (`pdo.dsn.*` など) を読むことができません。この場合は `false` を返します。

### 参考

- get_cfg_var() - PHP 設定オプションの値を取得する
- ini_get_all() - すべての設定オプションを得る
- ini_parse_quantity() - ini ディレクティブの省略形を解釈し、サイズを取得する
- ini_restore() - 設定オプションの値を元に戻す
- ini_set() - 設定オプションの値を設定する

# ini_get_all

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ini_get_all — すべての設定オプションを得る

### 説明

function 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_parse_quantity

(PHP 8 >= 8.2.0)

ini_parse_quantity — ini ディレクティブの省略形を解釈し、サイズを取得する

### 説明

function 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_restore

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_restore — 設定オプションの値を元に戻す

### 説明

function 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_set

(PHP 4, PHP 5, PHP 7, PHP 8)

ini_set — 設定オプションの値を設定する

### 説明

function 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() - 設定オプションの値を元に戻す
- 設定を変更するには

# memory_get_peak_usage

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

memory_get_peak_usage — PHP によって割り当てられたメモリの最大値を返す

### 説明

function 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

# memory_get_usage

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

memory_get_usage — PHP に割り当てられたメモリの量を返す

### 説明

function 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_reset_peak_usage

(PHP 8 >= 8.2.0)

memory_reset_peak_usage — メモリの最大値をリセットする

### 説明

function 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_loaded_file

(PHP 5 >= 5.2.4, PHP 7, PHP 8)

php_ini_loaded_file — 読み込まれた php.ini ファイルのパスを取得する

### 説明

function 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 の設定情報を出力する
- 設定ファイル

# php_ini_scanned_files

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

php_ini_scanned_files — 追加の ini ディレクトリにある .ini ファイルのリストを取得する

### 説明

function 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_sapi_name

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

php_sapi_name — ウェブサーバーと PHP の間のインターフェイスの型を返す

### 説明

function 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_uname

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

php_uname — PHP が稼動しているオペレーティングシステムに関する情報を返す

### 説明

function 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`

### 戻り値

説明を文字列で返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 無効な `mode` を指定した場合に、 ValueError をスローするようになりました。

### 例

例1 php_uname() の例

    <?php
    echo php_uname();
    echo PHP_OS;

    /* 出力の例
    Linux localhost 2.4.21-0.13mdk #1 Fri Mar 14 15:08:06 EST 2003 i686
    Linux

    FreeBSD localhost 3.2-RELEASE #15: Mon Dec 17 08:46:02 GMT 2001
    FreeBSD

    Windows NT XN1 5.1 build 2600
    WINNT
    */

    if (strtoupper(substr(PHP_OS, 0, 3)) === 'WIN') {
        echo 'このサーバーは Windows です!';
    } else {
        echo 'このサーバーは Windows ではありません!';
    }

    ?>

関連する 定義済みの定数 を使うほうが簡単なこともあります。例えばこのようになります。

例2 OS 関連の定数の例

    <?php
    // *nix
    echo DIRECTORY_SEPARATOR; // /
    echo PHP_SHLIB_SUFFIX;    // so
    echo PATH_SEPARATOR;      // :

    // Win*
    echo DIRECTORY_SEPARATOR; // \
    echo PHP_SHLIB_SUFFIX;    // dll
    echo PATH_SEPARATOR;      // ;
    ?>

### 参考

- phpversion() - 現在の PHP バージョンを取得する
- php_sapi_name() - ウェブサーバーと PHP の間のインターフェイスの型を返す
- phpinfo() - PHP の設定情報を出力する

# phpcredits

(PHP 4, PHP 5, PHP 7, PHP 8)

phpcredits — PHP に関するクレジットを出力する

### 説明

function 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 の設定情報を出力する

# phpinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

phpinfo — PHP の設定情報を出力する

### 説明

function 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() - コンパイル/ロードされている全てのモジュールの名前を配列として返す
- 定義済みの変数

# phpversion

(PHP 4, PHP 5, PHP 7, PHP 8)

phpversion — 現在の PHP バージョンを取得する

### 説明

function phpversion(?string `$extension` = `null`): string|false

現在動作中の PHP パーサーあるいは拡張モジュールのバージョンを表す文字列を返します。

### パラメータ

`extension`

  オプションで指定する拡張モジュール名。

### 戻り値

現在の PHP のバージョンを文字列で返します。 オプションの `extension` パラメータが文字列で指定されている場合、phpversion() はその拡張モジュールのバージョンを返します。 関連するバージョン情報が存在しない場合、 あるいは拡張モジュールが有効でない場合は `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `extension` は、nullable になりました。

### 例

例1 phpversion() の例

    <?php

    // たとえば 'Current PHP version: 8.3.12' などと表示します
    echo 'Current PHP version: ' . phpversion();

    // たとえば '1.22.3' などと表示します。拡張モジュールが有効でない場合は何も表示しません
    echo phpversion('zip');

    ?>

例2 `PHP_VERSION_ID` の例および使用法

    <?php

    /**
     * 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 のバージョンを取得する

# putenv

(PHP 4, PHP 5, PHP 7, PHP 8)

putenv — 環境変数の値を設定する

### 説明

function putenv(string `$assignment`): bool

サーバーの環境変数に `assignment` を追加します。 この環境変数は、カレントのリクエストを実行している間のみ存在します。 リクエスト終了時、環境変数は元の状態に戻されます。

### パラメータ

`assignment`

  `"FOO=BAR"` 形式の設定。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 例

例1 環境変数の設定

    <?php
    putenv("UNIQID=$uniqid");
    ?>

### 参考

- getenv() - 環境変数の値をひとつ、または全て取得する
- apache_setenv() - Apacheサブプロセスの環境変数を設定する

# 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 で 削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function restore_include_path(): void

include_path 設定値を php.ini でセットされたオリジナルの設定に戻します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

値を返しません。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | この関数は削除されました。
7.4.0 | この関数は推奨されなくなりました。

### 例

例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

# set_include_path

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

set_include_path — include_path 設定オプションをセットする

### 説明

function 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_time_limit

(PHP 4, PHP 5, PHP 7, PHP 8)

set_time_limit — 実行時間の最大値を制限する

### 説明

function 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

# sys_get_temp_dir

(PHP 5 >= 5.2.1, PHP 7, PHP 8)

sys_get_temp_dir — 一時ファイル用に使用されるディレクトリのパスを返す

### 説明

function 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() - 一意なファイル名を持つファイルを作成する

# version_compare

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

version_compare — ふたつの "PHP 標準" バージョン番号文字列を比較する

### 説明

function 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 を返す

# zend_thread_id

(PHP 5, PHP 7, PHP 8)

zend_thread_id — 現在のスレッドの一意な ID を返す

### 説明

function 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_version

(PHP 4, PHP 5, PHP 7, PHP 8)

zend_version — 現在の Zend Engine のバージョンを取得する

### 説明

function 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 バージョンを取得する

## 目次

- 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 — アサーションの値を調べる
  - 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 デバッガ

# はじめに

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.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_COLOR_PROMPT` (int)
`PHPDBG_COLOR_NOTICE` (int)
`PHPDBG_COLOR_ERROR` (int)

# phpdbg 関数

# phpdbg_break_file

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_file — ファイルの行にブレークポイントを挿入する

### 説明

function 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_function

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_function — 関数のエントリにブレークポイントを挿入する

### 説明

function phpdbg_break_function(string `$function`): void

指定された `function` のエントリにブレークポイントを挿入します。

### パラメータ

`function`
  関数の名前

### 戻り値

値を返しません。

### 参考

- phpdbg_break_file() - ファイルの行にブレークポイントを挿入する
- phpdbg_break_method() - メソッドのエントリにブレークポイントを挿入する
- phpdbg_break_next() - 次のオペコードにブレークポイントを挿入します
- phpdbg_clear() - 全てのブレークポイントをクリアする

# phpdbg_break_method

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_method — メソッドのエントリにブレークポイントを挿入する

### 説明

function 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_next

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

phpdbg_break_next — 次のオペコードにブレークポイントを挿入します

### 説明

function phpdbg_break_next(): void

次のオペコードにブレークポイントを挿入します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

値を返しません。

### 参考

- phpdbg_break_file() - ファイルの行にブレークポイントを挿入する
- phpdbg_break_function() - 関数のエントリにブレークポイントを挿入する
- phpdbg_break_method() - メソッドのエントリにブレークポイントを挿入する
- phpdbg_clear() - 全てのブレークポイントをクリアする

# phpdbg_clear

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_clear — 全てのブレークポイントをクリアする

### 説明

function phpdbg_clear(): void

これまでに設定されたブレークポイントをすべてクリアします。 phpdbg_break_*() 関数や、 コンソールで対話的に設定したブレークポイントが全て含まれます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

値を返しません。

### 参考

- phpdbg_break_file() - ファイルの行にブレークポイントを挿入する
- phpdbg_break_function() - 関数のエントリにブレークポイントを挿入する
- phpdbg_break_method() - メソッドのエントリにブレークポイントを挿入する
- phpdbg_break_next() - 次のオペコードにブレークポイントを挿入します

# phpdbg_color

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_color — 特定の要素に色を設定する

### 説明

function 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_end_oplog

(PHP 7, PHP 8)

phpdbg_end_oplog — oplog の終了

### 説明

function phpdbg_end_oplog(array `$options` = []): ?array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`options`

### 戻り値

# phpdbg_exec

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_exec — 実行コンテクストの設定を試みる

### 説明

function phpdbg_exec(string `$context`): string|bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`context`

### 戻り値

実行コンテクストが既に設定されていた場合、それを返します。 実行コンテクストが以前設定されたことがない場合、`true` を返します。 実行コンテクストを設定出来なかった場合、`false` を返し、 `E_WARNING` が発生します。

# phpdbg_get_executable

(PHP 7, PHP 8)

phpdbg_get_executable — 実行可能情報を取得

### 説明

function phpdbg_get_executable(array `$options` = []): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`options`

### 戻り値

# phpdbg_prompt

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

phpdbg_prompt — コマンドのプロンプトを設定する

### 説明

function phpdbg_prompt(string `$string`): void

コマンドのプロンプトを、指定された `string` に設定します。

### パラメータ

`string`
  コマンドのプロンプトとして使う文字列。

### 戻り値

値を返しません。

### 参考

- phpdbg_color() - 特定の要素に色を設定する

# phpdbg_start_oplog

(PHP 7, PHP 8)

phpdbg_start_oplog — oplog の開始

### 説明

function phpdbg_start_oplog(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

値を返しません。

## 目次

- phpdbg_break_file — ファイルの行にブレークポイントを挿入する
- phpdbg_break_function — 関数のエントリにブレークポイントを挿入する
- phpdbg_break_method — メソッドのエントリにブレークポイントを挿入する
- phpdbg_break_next — 次のオペコードにブレークポイントを挿入します
- phpdbg_clear — 全てのブレークポイントをクリアする
- phpdbg_color — 特定の要素に色を設定する
- phpdbg_end_oplog — oplog の終了
- phpdbg_exec — 実行コンテクストの設定を試みる
- phpdbg_get_executable — 実行可能情報を取得
- phpdbg_prompt — コマンドのプロンプトを設定する
- phpdbg_start_oplog — oplog の開始

- インストール/設定
  - 実行時設定
- 定義済み定数
- phpdbg 関数
  - phpdbg_break_file — ファイルの行にブレークポイントを挿入する
  - phpdbg_break_function — 関数のエントリにブレークポイントを挿入する
  - phpdbg_break_method — メソッドのエントリにブレークポイントを挿入する
  - phpdbg_break_next — 次のオペコードにブレークポイントを挿入します
  - phpdbg_clear — 全てのブレークポイントをクリアする
  - phpdbg_color — 特定の要素に色を設定する
  - phpdbg_end_oplog — oplog の終了
  - phpdbg_exec — 実行コンテクストの設定を試みる
  - phpdbg_get_executable — 実行可能情報を取得
  - phpdbg_prompt — コマンドのプロンプトを設定する
  - phpdbg_start_oplog — oplog の開始

# runkit7

# はじめに

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.

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定

## 要件

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

(PECL runkit7 >= Unknown)

runkit7_constant_add — Similar to define(), but allows defining in class definitions as well

### 説明

function 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

# runkit7_constant_redefine

(PECL runkit7 >= Unknown)

runkit7_constant_redefine — Redefine an already defined constant

### 説明

function 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

# runkit7_constant_remove

(PECL runkit7 >= Unknown)

runkit7_constant_remove — Remove/Delete an already defined constant

### 説明

function 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

# runkit7_function_add

(PECL runkit7 >= Unknown)

runkit7_function_add — Add a new function, similar to create_function()

### 説明

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

# runkit7_function_copy

(PECL runkit7 >= Unknown)

runkit7_function_copy — Copy a function to a new function name

### 説明

function 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

# runkit7_function_redefine

(PECL runkit7 >= Unknown)

runkit7_function_redefine — Replace a function definition with a new implementation

### 説明

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

# runkit7_function_remove

(PECL runkit7 >= Unknown)

runkit7_function_remove — Remove a function definition

### 説明

function 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

# runkit7_function_rename

(PECL runkit7 >= Unknown)

runkit7_function_rename — Change a function's name

### 説明

function 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

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

### 説明

function 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` を返します。

# runkit7_method_add

(PECL runkit7 >= Unknown)

runkit7_method_add — Dynamically adds a new method to a given class

### 説明

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

# runkit7_method_copy

(PECL runkit7 >= Unknown)

runkit7_method_copy — Copies a method from class to another

### 説明

function 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

# runkit7_method_redefine

(PECL runkit7 >= Unknown)

runkit7_method_redefine — Dynamically changes the code of the given method

### 説明

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

# runkit7_method_remove

(PECL runkit7 >= Unknown)

runkit7_method_remove — Dynamically removes the given method

### 説明

function 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

# runkit7_method_rename

(PECL runkit7 >= Unknown)

runkit7_method_rename — Dynamically changes the name of the given method

### 説明

function 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

# runkit7_object_id

(PECL runkit7 >= Unknown)

runkit7_object_id — Return the integer object handle for given object

### 説明

function 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() - 与えられたオブジェクトを扱う数値オブジェクトを返す

# runkit7_superglobals

(PECL runkit7 >= Unknown)

runkit7_superglobals — Return numerically indexed array of registered superglobals

### 説明

function 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

# runkit7_zval_inspect

(PECL runkit7 >= Unknown)

runkit7_zval_inspect — Returns information about the passed in value with data types, reference counts, etc

### 説明

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

## 目次

- 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

- インストール/設定
  - 要件
  - インストール手順
  - 実行時設定
- 定義済み定数
- 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

# Zend に対するユーザー操作

# はじめに

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 と互換性がありません。

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定

## 要件

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

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_add_function — Adds non-existent function or method

### 説明

function uopz_add_function(string `$function`, Closure `$handler`, int `&$flags` = ZEND_ACC_PUBLIC): bool
function 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

# uopz_allow_exit

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_allow_exit — Allows control over disabled exit opcode

### 説明

function 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

# uopz_backup

(PECL uopz 1 >= 1.0.3, PECL uopz 2)

uopz_backup — Backup a function

警告

この関数は、PECL uopz 5.0.0 で 削除 されました。

### 説明

function uopz_backup(string `$function`): void
function 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)

# uopz_compose

(PECL uopz 1, PECL uopz 2)

uopz_compose — Compose a class

警告

この関数は、PECL uopz 5.0.0 で 削除 されました。

### 説明

function 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"
    }

# uopz_copy

(PECL uopz 1 >= 1.0.4, PECL uopz 2)

uopz_copy — Copy a function

警告

この関数は、PECL uopz 5.0.0 で 削除 されました。

### 説明

function uopz_copy(string `$function`): Closure
function 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"

# uopz_del_function

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_del_function — Deletes previously added function or method

### 説明

function uopz_del_function(string `$function`): bool
function 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

# uopz_delete

(PECL uopz 1, PECL uopz 2)

uopz_delete — Delete a function

警告

この関数は、PECL uopz 5.0.0 で 削除 されました。

### 説明

function uopz_delete(string `$function`): void
function 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_extend

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7 < 7.1.0)

uopz_extend — 実行時にクラスを継承させる

### 説明

function uopz_extend(string `$class`, string `$parent`): bool

`class` に `parent` を継承させます。

### パラメータ

`class`

  拡張するクラスの名前

`parent`

  継承するクラスの名前

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### エラー / 例外

PHP 7.4.0 以降では、 OPcache が有効になっており、 かつ `class` または `parent` が変更不能な場合(トレイトの場合も)、 uopz_extend() 関数は 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_flags

(PECL uopz 2 >= 2.0.2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_flags — 関数またはクラスのフラグを 取得/設定 する

### 説明

function uopz_flags(string `$function`, int `$flags` = PHP_INT_MAX): int
function 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)

# uopz_function

(PECL uopz 1, PECL uopz 2)

uopz_function — Creates a function at runtime

警告

この関数は、PECL uopz 5.0.0 で 削除 されました。

### 説明

function uopz_function(string `$function`, Closure `$handler`, int `$modifiers` = ?): void
function 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

# uopz_get_exit_status

(PECL uopz 5, PECL uopz , PECL uopz 7)

uopz_get_exit_status — Retrieve the last set exit status

### 説明

function 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

# uopz_get_hook

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_hook — Gets previously set hook on function or method

### 説明

function uopz_get_hook(string `$function`): Closure
function 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

# uopz_get_mock

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_mock — Get the current mock for a class

### 説明

function 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() - 以前に設定したモックを削除する

# uopz_get_property

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_property — Gets value of class or instance property

### 説明

function uopz_get_property(string `$class`, string `$property`): mixed
function 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

# uopz_get_return

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_return — Gets a previous set return value for a function

### 説明

function uopz_get_return(string `$function`): mixed
function 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

# uopz_get_static

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_get_static — 関数またはメソッドスコープから、static変数を取得する

### 説明

function uopz_get_static(string `$class`, string `$function`): array
function 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_implement

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7 < 7.1.0)

uopz_implement — 実行時にインターフェイスを実装させる

### 説明

function uopz_implement(string `$class`, string `$interface`): bool

`class` に`interface` を実装させます。

### パラメータ

`class`

`interface`

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### エラー / 例外

PHP 7.4.0 以降では、 OPcache が有効になっており、 かつ `class` のエントリが変更不能な場合、 uopz_implement() 関数は 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"
    }

# uopz_overload

(PECL uopz 1, PECL uopz 2)

uopz_overload — Overload a VM opcode

警告

この関数は、PECL uopz 5.0.0 で 削除 されました。

### 説明

function 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_redefine

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_redefine — 定数を再定義

### 説明

function uopz_redefine(string `$constant`, mixed `$value`): bool
function 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

# uopz_rename

(PECL uopz 1, PECL uopz 2)

uopz_rename — Rename a function at runtime

警告

この関数は、PECL uopz 5.0.0 で 削除 されました。

### 説明

function uopz_rename(string `$function`, string `$rename`): void
function 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

# uopz_restore

(PECL uopz 1 >= 1.0.3, PECL uopz 2)

uopz_restore — Restore a previously backed up function

警告

この関数は、PECL uopz 5.0.0 で 削除 されました。

### 説明

function uopz_restore(string `$function`): void
function 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

# 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

### 説明

function uopz_set_hook(string `$function`, Closure `$hook`): bool
function 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_mock

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_mock — 新しいオブジェクトを生成する際に、クラスの代わりにモックを使う

### 説明

function uopz_set_mock(string `$class`, mixed `$mock`): void

`mock` がクラス名を含んだ文字列だった場合、 `class` の代わりにそれがインスタンス化されます。 `mock` はオブジェクトであっても構いません。

> 注意:

> プロパティやメソッドに動的にアクセスした場合にだけ、 `mock` オブジェクトを使います。 静的にアクセスした場合には、オリジナルの `class` を使います。 後に示す 例 を参照ください。

### パラメータ

`class`

  モックで代替するクラスの名前

`mock`

  モックとして使うクラス名を含む文字列。またはオブジェクト。 文字列を渡す場合、完全修飾されたクラス名でなければいけません。 この場合、マジック定数 `::class` を使うことを推奨します。

### 戻り値

値を返しません。

### 変更履歴

バージョン | 説明
--- | ---
PECL 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() - 以前に設定したモックを削除する

# uopz_set_property

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_property — Sets value of existing class or instance property

### 説明

function uopz_set_property(string `$class`, string `$property`, mixed `$value`): void
function 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

# uopz_set_return

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_set_return — Provide a return value for an existing function

### 説明

function uopz_set_return(string `$function`, mixed `$value`, bool `$execute` = `false`): bool
function 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

# uopz_set_static

(PECL uopz 5, PECL uopz , PECL uopz 7)

uopz_set_static — Sets the static variables in function or method scope

### 説明

function uopz_set_static(string `$function`, array `$static`): void
function 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_undefine

(PECL uopz 1, PECL uopz 2, PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_undefine — 定数を未定義化

### 説明

function uopz_undefine(string `$constant`): bool
function 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)

# uopz_unset_hook

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_unset_hook — Removes previously set hook on function or method

### 説明

function uopz_unset_hook(string `$function`): bool
function 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_mock

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_unset_mock — 以前に設定したモックを削除する

### 説明

function 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

# uopz_unset_return

(PECL uopz 5, PECL uopz 6, PECL uopz 7)

uopz_unset_return — Unsets a previously set return value for a function

### 説明

function uopz_unset_return(string `$function`): bool
function 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

## 目次

- 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 関数
  - 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

# PHP 用の Windows キャッシュ

# はじめに

Windows Cache Extension for PHP は、PHP のアクセラレータです。 Windows および Windows サーバー上での PHP アプリケーションの動作速度を向上させます。 Windows Cache Extension for PHP を有効にして PHP エンジンに読み込むと、 PHP アプリケーションのコードに一切手を加えずに恩恵を受けることができます。

Windows Cache Extension には 5 種類のキャッシュが含まれています。 それぞれのキャッシュ型の目的と利点を以下にまとめました。

- PHP Opcode キャッシュ - PHP はスクリプト処理エンジンです。 テキストや PHP の命令からなるデータストリームを入力として読み込み、 別の形式 (通常は HTML 形式) のデータストリームを生成します。 つまり、ウェブクライアントからのリクエストを受け取るたびに、 PHP エンジンが PHP スクリプトの読み込みとパース、コンパイルそして実行を行っているわけです。 読み込み、パースそしてコンパイルはウェブサーバーの CPU やファイルシステムに負荷をかけ、 PHP ウェブアプリケーション全体のパフォーマンスに影響を及ぼします。 PHP バイトコード (opcode) キャッシュを使うと、コンパイル済みのスクリプトのバイトコードを共有メモリに置きます。 同じスクリプトが再びリクエストされたときには、PHP エンジンはこのバイトコードを再利用します。

  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

(PECL wincache >= 1.0.0)

wincache_fcache_fileinfo — ファイルキャッシュにキャッシュされたファイルについての情報を取得する

### 説明

function 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_meminfo

(PECL wincache >= 1.0.0)

wincache_fcache_meminfo — ファイルキャッシュのメモリ使用状況についての情報を取得する

### 説明

function 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_lock

(PECL wincache >= 1.1.0)

wincache_lock — 指定したキーで排他ロックを確保する

### 説明

function 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() - セッションキャッシュにキャッシュされたファイルについての情報を取得する

# wincache_ocache_fileinfo

(PECL wincache >= 1.0.0)

wincache_ocache_fileinfo — opcode キャッシュにキャッシュされたファイルについての情報を取得する

### 説明

function 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() - セッションキャッシュのメモリ使用状況についての情報を取得する

# wincache_ocache_meminfo

(PECL wincache >= 1.0.0)

wincache_ocache_meminfo — opcode キャッシュのメモリ使用状況についての情報を取得する

### 説明

function 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_refresh_if_changed

(PECL wincache >= 1.0.0)

wincache_refresh_if_changed — キャッシュされたファイルのキャッシュエントリをリフレッシュする

### 説明

function 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_rplist_fileinfo

(PECL wincache >= 1.0.0)

wincache_rplist_fileinfo — ファイルパス解決キャッシュについての情報を取得する

### 説明

function 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_meminfo

(PECL wincache >= 1.0.0)

wincache_rplist_meminfo — ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する

### 説明

function 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_scache_info

(PECL wincache >= 1.1.0)

wincache_scache_info — セッションキャッシュにキャッシュされたファイルについての情報を取得する

### 説明

function 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_meminfo

(PECL wincache >= 1.1.0)

wincache_scache_meminfo — セッションキャッシュのメモリ使用状況についての情報を取得する

### 説明

function 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_ucache_add

(PECL wincache >= 1.1.0)

wincache_ucache_add — 変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加する

### 説明

function wincache_ucache_add(string `$key`, mixed `$value`, int `$ttl` = 0): bool
function 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_cas

(PECL wincache >= 1.1.0)

wincache_ucache_cas — 変数を古い値と比較して新しい値を代入する

### 説明

function 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_clear

(PECL wincache >= 1.1.0)

wincache_ucache_clear — ユーザーキャッシュの中身全体を削除する

### 説明

function 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_dec

(PECL wincache >= 1.1.0)

wincache_ucache_dec — キーに関連づけられた値を減少させる

### 説明

function 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_delete

(PECL wincache >= 1.1.0)

wincache_ucache_delete — 変数をユーザーキャッシュから削除する

### 説明

function 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_exists

(PECL wincache >= 1.1.0)

wincache_ucache_exists — 変数がユーザーキャッシュに存在するかどうかを調べる

### 説明

function 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_get

(PECL wincache >= 1.1.0)

wincache_ucache_get — ユーザーキャッシュに格納された変数を取得する

### 説明

function 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_inc

(PECL wincache >= 1.1.0)

wincache_ucache_inc — キーに関連づけられた値を増加させる

### 説明

function 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_info

(PECL wincache >= 1.1.0)

wincache_ucache_info — ユーザーキャッシュにキャッシュされたファイルについての情報を取得する

### 説明

function 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_meminfo

(PECL wincache >= 1.1.0)

wincache_ucache_meminfo — ユーザーキャッシュのメモリ使用状況についての情報を取得する

### 説明

function 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_set

(PECL wincache >= 1.1.0)

wincache_ucache_set — 変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする

### 説明

function wincache_ucache_set(mixed `$key`, mixed `$value`, int `$ttl` = 0): bool
function 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_unlock

(PECL wincache >= 1.1.0)

wincache_unlock — 指定したキーの排他ロックを解放する

### 説明

function 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_fcache_fileinfo — ファイルキャッシュにキャッシュされたファイルについての情報を取得する
- wincache_fcache_meminfo — ファイルキャッシュのメモリ使用状況についての情報を取得する
- wincache_lock — 指定したキーで排他ロックを確保する
- wincache_ocache_fileinfo — opcode キャッシュにキャッシュされたファイルについての情報を取得する
- wincache_ocache_meminfo — opcode キャッシュのメモリ使用状況についての情報を取得する
- wincache_refresh_if_changed — キャッシュされたファイルのキャッシュエントリをリフレッシュする
- wincache_rplist_fileinfo — ファイルパス解決キャッシュについての情報を取得する
- wincache_rplist_meminfo — ファイルパス解決キャッシュのメモリ使用状況についての情報を取得する
- wincache_scache_info — セッションキャッシュにキャッシュされたファイルについての情報を取得する
- wincache_scache_meminfo — セッションキャッシュのメモリ使用状況についての情報を取得する
- wincache_ucache_add — 変数が既にキャッシュに存在しない場合にのみ変数をユーザーキャッシュに追加する
- wincache_ucache_cas — 変数を古い値と比較して新しい値を代入する
- wincache_ucache_clear — ユーザーキャッシュの中身全体を削除する
- wincache_ucache_dec — キーに関連づけられた値を減少させる
- wincache_ucache_delete — 変数をユーザーキャッシュから削除する
- wincache_ucache_exists — 変数がユーザーキャッシュに存在するかどうかを調べる
- wincache_ucache_get — ユーザーキャッシュに格納された変数を取得する
- wincache_ucache_inc — キーに関連づけられた値を増加させる
- wincache_ucache_info — ユーザーキャッシュにキャッシュされたファイルについての情報を取得する
- wincache_ucache_meminfo — ユーザーキャッシュのメモリ使用状況についての情報を取得する
- wincache_ucache_set — 変数をユーザーキャッシュに追加し、変数が既にキャッシュに存在する場合はそれを上書きする
- wincache_unlock — 指定したキーの排他ロックを解放する

# Windows でのビルド

## 目次

- 要件
- コンパイルおよびビルド
- ビルドの検証

## 要件

WinCache 拡張モジュールのビルドには、以下が必要です。

1. PHP のソースコード
2. PHP のビルド環境
3. WinCache のソースコード

最初のふたつについては、 » Windows での PHP のビルド に書かれている手順に従いましょう。

WinCache のソースコードは、 PECL 拡張モジュールをダウンロードする に書かれている指示に従って取得します。

## コンパイルおよびビルド

WinCache を Windows OS 上でコンパイル・ビルドする手順は次のとおりです。

1. PHP のビルドに使うコマンドプロンプトを開く

2. PHP ソースのルートフォルダに移動する

3. 次のコマンドを実行する

       cscript.exe win32\build\buildconf.js

4. 次のコマンドを実行する

       configure.bat --help

   この出力には新しいフラグ `--enable-wincache` が含まれています。

5. 次のコマンドを実行する

       configure.js [all options used to build PHP] --enable-wincache

   `--enable-wincache` は、WinCache 拡張モジュールを正しくビルドするために必要な唯一の追加オプションです。 このオプションは、WinCache をビルドして PHP の dll にスタティックリンクします。 WinCache 拡張モジュールを単体の DLL とｈしてビルドするには、オプション `--enable-wincache=shared` を指定します。

6. 次のコマンドを実行する

       nmake

## ビルドの検証

WinCache が正しくビルドできたことを確かめる手順は次のとおりです。

1. PHP のバイナリがビルドされたフォルダに移動する

2. 次のコマンドを実行する

       php.exe -n -d extension=php_wincache.dll -re wincache

   WinCache が正しくビルドされていれば、このコマンドは WinCache がサポートする INI ディレクティブと関数の一覧を出力します。

- インストール/設定
  - 要件
  - インストール手順
  - 実行時設定
  - 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 でのビルド
  - 要件
  - コンパイルおよびビルド
  - ビルドの検証

# 階層型プロファイラ

# はじめに

XHProf は、軽量で階層型な命令ベースのプロファイラです。 データ収集フェーズでは、呼び出し回数や プログラムの動的コールグラフ内の弧の包括的メトリクスを追跡します。 排他的メトリクス (実行時間や CPU 時間、メモリ使用量など) の計算は、レポーティングや後処理のフェーズで行います。 関数のプロファイルは、呼び出す側と呼び出される側に分けることができます。 XHProf が再帰関数を扱うときには、コールグラフ内での循環をデータ収集時に検出し、 循環を回避するために、再帰の実行のたびにその深さも含めた一意な名前をつけます。

XHProf には、シンプルな HTML ベースのユーザーインターフェイス (PHP で書かれたもの) が含まれています。 ブラウザ上でプロファイル結果を見られるので、結果を見たり他人と共有したりが簡単にできるようになります。 コールグラフの画像表示にも対応しています。

XHProf のレポートは、実行されたコードの構造を把握するのにも便利です。 レポートは階層構造になっているので、これを利用して、 たとえば特定の関数が呼ばれるに至るまでの関数呼び出しの流れをたどることもできます。

XHProf には、二回の実行結果を比較 ("diff" レポート) したり、複数回実行した結果を集約したりする機能もあります。 差分のレポートや集約レポートに関しても、単一の実行レポートと同様に 「フラット」な表示と「階層型」の表示でプロファイルを確認できます。

詳細な情報は » xhprof の facebook ページ を参照ください。

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定

## 要件

必須ではありませんが、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

(PECL xhprof >= 0.9.0)

xhprof_disable — xhprof プロファイラを終了する

### 説明

function xhprof_disable(): ?array

プロファイラを終了して、xhprof の実行結果データを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

実行結果の xhprof データを配列で返します。 プロファイリングが有効でない場合、`null` を返します。

### 例

例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_enable

(PECL xhprof >= 0.9.0)

xhprof_enable — xhprof プロファイラを開始する

### 説明

function 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_sample_disable

(PECL xhprof >= 0.9.0)

xhprof_sample_disable — xhprof サンプルプロファイラを終了する

### 説明

function xhprof_sample_disable(): ?array

サンプルモードの xhprof プロファイラを終了し、プロファイルの情報を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

xhprof のサンプルデータの配列を返します。 プロファイリングが有効でない場合、`null` を返します。

### 例

例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_sample_enable

(PECL xhprof >= 0.9.0)

xhprof_sample_enable — サンプリングモードでの XHProf プロファイリングを開始する

### 説明

function xhprof_sample_enable(): void

サンプルモードでのプロファイルを開始します。これは xhprof_enable() の軽量版です。 サンプリング間隔は 0.1 秒で、完全な関数のコールスタックを記録します。 主な使い道は、パフォーマンス監視や調査などでオーバーヘッドを極力抑えたい場合です。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

`null`

### 参考

- xhprof_sample_disable() - xhprof サンプルプロファイラを終了する
- xhprof_enable() - xhprof プロファイラを開始する
- memory_get_usage() - PHP に割り当てられたメモリの量を返す
- getrusage() - 現在のリソース使用状況を取得する

## 目次

- xhprof_disable — xhprof プロファイラを終了する
- xhprof_enable — xhprof プロファイラを開始する
- xhprof_sample_disable — xhprof サンプルプロファイラを終了する
- xhprof_sample_enable — サンプリングモードでの XHProf プロファイリングを開始する

- インストール/設定
  - 要件
  - インストール手順
  - 実行時設定
- 定義済み定数
- 例
- Xhprof 関数
  - xhprof_disable — xhprof プロファイラを終了する
  - xhprof_enable — xhprof プロファイラを開始する
  - xhprof_sample_disable — xhprof サンプルプロファイラを終了する
  - xhprof_sample_enable — サンプリングモードでの XHProf プロファイリングを開始する

# Yac

# はじめに

Yac (Yet Another cache), is a lock-free, shared memory user data cache, could be used to replace APC, local memcache.

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定
- リソース型

## 要件

## インストール手順

この » 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 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

`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 function __construct(string `$prefix` = "")
public function add(string `$keys`, mixed `$value`, int `$ttl` = 0): bool
public function add(array `$key_vals`): bool
public function delete(string|array `$keys`, int `$ttl` = ?): bool
public function dump(int `$$num`): mixed
public function flush(): bool
public function get(string|array `$key`, int `&$cas` = `null`): mixed
public function __get(string `$key`): mixed
public function info(): array
public function set(string `$keys`, mixed `$value`, int `$ttl` = 0): bool
public function add(array `$key_vals`): bool
public function __set(string `$keys`, mixed `$value`): mixed
}

## プロパティ

_prefix

# Yac::add

(PECL yac >= 1.0.0)

Yac::add — Store into cache

### 説明

public function Yac::add(string `$keys`, mixed `$value`, int `$ttl` = 0): bool
public function 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 resource

`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", "value"));

# Yac::__construct

(PECL yac >= 1.0.0)

Yac::__construct — Constructor

### 説明

public function 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.

# Yac::delete

(PECL yac >= 1.0.0)

Yac::delete — Remove items from cache

### 説明

public function 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.

### 戻り値

# Yac::dump

(PECL yac >= 1.0.0)

Yac::dump — Dump cache

### 説明

public function Yac::dump(int `$$num`): mixed

Dump values stored in cache

### パラメータ

`num`

  Maximum number of items should be returned

### 戻り値

mixed

# Yac::flush

(PECL yac >= 1.0.0)

Yac::flush — Flush the cache

### 説明

public function Yac::flush(): bool

Remove all cached values

### パラメータ

この関数にはパラメータはありません。

### 戻り値

bool, always true

# Yac::get

(PECL yac >= 1.0.0)

Yac::get — Retrieve values from cache

### 説明

public function 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

# Yac::__get

(PECL yac >= 1.0.0)

Yac::__get — Getter

### 説明

public function Yac::__get(string `$key`): mixed

Retrieve values from cache

### パラメータ

`key`

  string key

### 戻り値

mixed on success, `null` on failure

# Yac::info

(PECL yac >= 1.0.0)

Yac::info — Status of cache

### 説明

public function 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"

# Yac::set

(PECL yac >= 1.0.0)

Yac::set — Store into cache

### 説明

public function Yac::set(string `$keys`, mixed `$value`, int `$ttl` = 0): bool
public function 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 resource

`ttl`

  expire time

### 戻り値

the value self

# Yac::__set

(PECL yac >= 1.0.0)

Yac::__set — Setter

### 説明

public function 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 resource

### 戻り値

Always return the value self

## 目次

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

- 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 — 外部関数インターフェース
  - インストール/設定
  - 例
  - FFI — C のコードやデータへの主要インターフェース
  - FFI\CData — C のデータハンドル
  - FFI\CType — C の型ハンドル
  - FFI\Exception — FFI 例外
  - FFI\ParserException — FFI パーサー例外
- 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

# 音声フォーマットの操作

# OpenAL 音声バインディング

# はじめに

プラットフォームに依存しない音声バインディングです。 » 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

(PECL openal >= 0.1.0)

openal_buffer_create — OpenAL バッファを生成する

### 説明

function openal_buffer_create(): resource

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に Open AL (バッファ) リソース、失敗した場合に `false` を返します。

### 参考

- openal_buffer_loadwav() - .wav ファイルをバッファに読み込む
- openal_buffer_data() - バッファのデータを読み込む

# openal_buffer_data

(PECL openal >= 0.1.0)

openal_buffer_data — バッファのデータを読み込む

### 説明

function 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_buffer_destroy

(PECL openal >= 0.1.0)

openal_buffer_destroy — OpenAL バッファを削除する

### 説明

function openal_buffer_destroy(resource `$buffer`): bool

### パラメータ

`buffer`
  Open AL (バッファ) リソース (事前に openal_buffer_create() で作成したもの)。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- openal_buffer_create() - OpenAL バッファを生成する

# openal_buffer_get

(PECL openal >= 0.1.0)

openal_buffer_get — OpenAL バッファのプロパティを取得する

### 説明

function 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 バッファを生成する

# openal_buffer_loadwav

(PECL openal >= 0.1.0)

openal_buffer_loadwav — .wav ファイルをバッファに読み込む

### 説明

function openal_buffer_loadwav(resource `$buffer`, string `$wavfile`): bool

### パラメータ

`buffer`
  Open AL (バッファ) リソース (事前に openal_buffer_create() で作成したもの)。
`wavfile`
  ローカルファイルシステム上の .wav ファイルへのパス。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- openal_buffer_data() - バッファのデータを読み込む
- openal_stream() - ソースのストリーム再生を開始する

# openal_context_create

(PECL openal >= 0.1.0)

openal_context_create — 音声処理コンテキストを作成する

### 説明

function openal_context_create(resource `$device`): resource

### パラメータ

`device`
  Open AL (デバイス) リソース (事前に openal_device_open() で作成したもの)。

### 戻り値

成功した場合に Open AL (コンテキスト) リソース、 失敗した場合に `false` を返します。

### 参考

- openal_device_open() - OpenAL 音声レイヤを初期化する
- openal_context_destroy() - コンテキストを削除する

# openal_context_current

(PECL openal >= 0.1.0)

openal_context_current — 指定したコンテキストを現在のコンテキストにする

### 説明

function openal_context_current(resource `$context`): bool

### パラメータ

`context`
  Open AL (コンテキスト) リソース (事前に openal_context_create() で作成したもの)。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- openal_context_create() - 音声処理コンテキストを作成する

# openal_context_destroy

(PECL openal >= 0.1.0)

openal_context_destroy — コンテキストを削除する

### 説明

function openal_context_destroy(resource `$context`): bool

### パラメータ

`context`
  Open AL (コンテキスト) リソース (事前に openal_context_create() で作成したもの)。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- openal_context_create() - 音声処理コンテキストを作成する

# openal_context_process

(PECL openal >= 0.1.0)

openal_context_process — 指定したコンテキストを処理する

### 説明

function 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_suspend

(PECL openal >= 0.1.0)

openal_context_suspend — 指定したコンテキストをサスペンドする

### 説明

function openal_context_suspend(resource `$context`): bool

### パラメータ

`context`
  Open AL (コンテキスト) リソース (事前に openal_context_create() で作成したもの)。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- openal_context_create() - 音声処理コンテキストを作成する
- openal_context_current() - 指定したコンテキストを現在のコンテキストにする
- openal_context_process() - 指定したコンテキストを処理する

# openal_device_close

(PECL openal >= 0.1.0)

openal_device_close — OpenAL デバイスを閉じる

### 説明

function openal_device_close(resource `$device`): bool

### パラメータ

`device`
  閉じようとしている Open AL (デバイス) リソース (事前に openal_device_open() で作成したもの)。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- openal_device_open() - OpenAL 音声レイヤを初期化する

# openal_device_open

(PECL openal >= 0.1.0)

openal_device_open — OpenAL 音声レイヤを初期化する

### 説明

function openal_device_open(string `$device_desc` = ?): resource

### パラメータ

`device_desc`
  `device_desc` で指定した音声デバイスをオープンします。 `device_desc` が指定されなかった場合は、 最初に見つかった音声デバイスが使用されます。

### 戻り値

成功した場合に Open AL (デバイス) リソース、 失敗した場合に `false` を返します。

### 参考

- openal_device_close() - OpenAL デバイスを閉じる
- openal_context_create() - 音声処理コンテキストを作成する

# openal_listener_get

(PECL openal >= 0.1.0)

openal_listener_get — リスナーのプロパティを取得する

### 説明

function 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_set

(PECL openal >= 0.1.0)

openal_listener_set — リスナーのプロパティを設定する

### 説明

function 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_source_create

(PECL openal >= 0.1.0)

openal_source_create — ソースリソースを生成する

### 説明

function openal_source_create(): resource

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に Open AL (ソース) リソース、 失敗した場合に `false` を返します。

### 参考

- openal_source_set() - ソースのプロパティを設定する
- openal_source_play() - ソースの再生を開始する
- openal_source_destroy() - ソースリソースを削除する

# openal_source_destroy

(PECL openal >= 0.1.0)

openal_source_destroy — ソースリソースを削除する

### 説明

function openal_source_destroy(resource `$source`): bool

### パラメータ

`source`
  Open AL (ソース) リソース (事前に openal_source_create() で作成したもの)。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- openal_source_create() - ソースリソースを生成する

# openal_source_get

(PECL openal >= 0.1.0)

openal_source_get — OpenAL ソースのプロパティを取得する

### 説明

function 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_pause

(PECL openal >= 0.1.0)

openal_source_pause — ソースを一時停止する

### 説明

function 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_play

(PECL openal >= 0.1.0)

openal_source_play — ソースの再生を開始する

### 説明

function 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_rewind

(PECL openal >= 0.1.0)

openal_source_rewind — ソースを巻き戻す

### 説明

function 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_set

(PECL openal >= 0.1.0)

openal_source_set — ソースのプロパティを設定する

### 説明

function 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_stop

(PECL openal >= 0.1.0)

openal_source_stop — ソースの再生を停止する

### 説明

function openal_source_stop(resource `$source`): bool

### パラメータ

`source`
  Open AL (ソース) リソース (事前に openal_source_create() で作成したもの)。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- openal_source_play() - ソースの再生を開始する
- openal_source_pause() - ソースを一時停止する
- openal_source_rewind() - ソースを巻き戻す

# openal_stream

(PECL openal >= 0.1.0)

openal_stream — ソースのストリーム再生を開始する

### 説明

function 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() - バイナリセーフなファイル書き込み処理

## 目次

- 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_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 関数

# 認証サービス

# Radius

# はじめに

このパッケージは、FreeBSD の libradius (Remote Authentication Dial In User Service) をもとにしたものです。 クライアントからの認証や課金を、ネットワーク越しのリモートサーバーに行うことができます。

この PECL モジュールは、Radius 認証 (» RFC 2865) および Radius 課金 (» RFC 2866) を完全にサポートします。 このパッケージは、Unix (FreeBSD および Linux でテストしました) および Windows で使用可能です。

> 注意: libradius に関する正確な説明は» ここ にあります。設定ファイルについての詳細な説明は » ここです。

# インストール/設定

## 目次

- インストール手順

## インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/radius.

# 定義済み定数

## 目次

- 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

(PECL radius >= 1.1.0)

radius_acct_open — 課金用の Radius ハンドルを作成する

### 説明

function radius_acct_open(): resource

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合にハンドル、エラー時に `false` を返します。 この関数が失敗するのは、無効なメモリを使用した場合のみです。

### 例

例1 radius_acct_open() の例

    <?php
    $res = radius_acct_open ()
        or die ("ハンドルを作成できませんでした");
    print "ハンドルの作成に成功しました";
    ?>

# radius_add_server

(PECL radius >= 1.1.0)

radius_add_server — サーバーを追加する

### 説明

function 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_auth_open

(PECL radius >= 1.1.0)

radius_auth_open — 認証用の Radius ハンドルを作成する

### 説明

function radius_auth_open(): resource

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合にハンドル、エラー時に `false` を返します。 この関数が失敗するのは、無効なメモリを使用した場合のみです。

### 例

例1 radius_auth_open() の例

    <?php
    $radh = radius_auth_open()
        or die ("ハンドルを作成できませんでした");
    echo "ハンドルの作成に成功しました";
    ?>

# radius_close

(PECL radius >= 1.1.0)

radius_close — すべてのリソースを開放する

### 説明

function radius_close(resource `$radius_handle`): bool

各リクエストの終了時に PHP がすべてのリソースを開放するので、 この関数をコールする必要はありません。

### パラメータ

`radius_handle`
  RADIUS リソース。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

# radius_config

(PECL radius >= 1.1.0)

radius_config — 指定した設定ファイルをライブラリに読み込ませる

### 説明

function 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_create_request

(PECL radius >= 1.1.0)

radius_create_request — 課金あるいは認証のリクエストを作成する

### 説明

function 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() - リクエストを送信し、応答を待つ

# radius_cvt_addr

(PECL radius >= 1.1.0)

radius_cvt_addr — 生データを IP アドレスに変換する

### 説明

function 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_int

(PECL radius >= 1.1.0)

radius_cvt_int — 生データを整数に変換する

### 説明

function 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_string

(PECL radius >= 1.1.0)

radius_cvt_string — 生データを文字列に変換する

### 説明

function 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_demangle

(PECL radius >= 1.2.0)

radius_demangle — データを復元する

### 説明

function radius_demangle(resource `$radius_handle`, string `$mangled`): string

セキュリティ上の理由により、(パスワード、MS-CHAPv1 MPPE キーなど) いくつかのデータは変形されます。それを使用する際には事前に復元する 必要があります。

### パラメータ

`radius_handle`
  RADIUS リソース。
`mangled`
  復元対象のデータ

### 戻り値

復元した文字列、あるいはエラー時には `false` を返します。

# radius_demangle_mppe_key

(PECL radius >= 1.2.0)

radius_demangle_mppe_key — 変形されたデータから mppe キーを得る

### 説明

function radius_demangle_mppe_key(resource `$radius_handle`, string `$mangled`): string

MS-CHAPv2 で MPPE を使用している場合には、送信キーおよび受信キーが 変形されます (» RFC 2548 を参照ください)。しかしこの関数は無意味です。なぜなら PHP では PPTP-MPPE は実装されていないし、今後も実装されるとは思えないからです。

### パラメータ

`radius_handle`
  RADIUS リソース。
`mangled`
  復元対象のデータ

### 戻り値

復元したデータ、あるいはエラー時には `false` を返します。

# radius_get_attr

(PECL radius >= 1.1.0)

radius_get_attr — 属性を取得する

### 説明

function radius_get_attr(resource `$radius_handle`): mixed

Radius リクエストと同様、各レスポンスもゼロ個以上の属性を含んでいます。 radius_send_request() でレスポンスを受け取ったら、 radius_get_attr() を使用して各属性を抽出することが できます。radius_get_attr() がコールされるたびに、 現在のレスポンスから次の属性を取得します。

### パラメータ

`radius_handle`
  RADIUS リソース。

### 戻り値

属性の型とデータを含む連想配列、あるいは 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() - リクエストを送信し、応答を待つ

# radius_get_tagged_attr_data

(PECL radius >= 1.3.0)

radius_get_tagged_attr_data — Extracts the data from a tagged attribute

### 説明

function 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

# radius_get_tagged_attr_tag

(PECL radius >= 1.3.0)

radius_get_tagged_attr_tag — Extracts the tag from a tagged attribute

### 説明

function 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_vendor_attr

(PECL radius >= 1.1.0)

radius_get_vendor_attr — ベンダ固有の属性を取得する

### 説明

function 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() - ベンダー固有のバイナリ属性を設定する

# radius_put_addr

(PECL radius >= 1.1.0)

radius_put_addr — IP アドレス属性を設定する

### 説明

function radius_put_addr(
resource `$radius_handle`,
int `$type`,
string `$addr`,
int `$options` = 0,
int `$tag` = ?
): bool

IP アドレス属性を、現在の RADIUS リクエストにアタッチします。

> 注意: リクエストを radius_create_request() で作ってからでないと、この関数は呼べません。

### パラメータ

`radius_handle`
  RADIUS リソース。
`type`
  属性の型。
`addr`
  IPv4 アドレスを表す文字列。 `10.0.0.1` など。
`options`
  属性のオプションのビットマスク。使えるオプションには、`RADIUS_OPTION_TAGGED` や `RADIUS_OPTION_SALT` があります。
`tag`
  属性のタグ。`RADIUS_OPTION_TAGGED` が設定されていない限り、このパラメータは無視されます。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
PECL radius 1.3.0 | `options` および `tag` が追加されました。

# radius_put_attr

(PECL radius >= 1.1.0)

radius_put_attr — バイナリ属性を設定する

### 説明

function radius_put_attr(
resource `$radius_handle`,
int `$type`,
string `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

バイナリ属性を、現在の RADIUS リクエストにアタッチします。

> 注意: リクエストを radius_create_request() で作ってからでないと、この関数は呼べません。

### パラメータ

`radius_handle`
  RADIUS リソース。
`type`
  属性の型。
`value`
  属性の値。バイナリ文字列として扱われます。
`options`
  属性のオプションのビットマスク。使えるオプションには、`RADIUS_OPTION_TAGGED` や `RADIUS_OPTION_SALT` があります。
`tag`
  属性のタグ。`RADIUS_OPTION_TAGGED` が設定されていない限り、このパラメータは無視されます。

### 戻り値

成功した場合に `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_int

(PECL radius >= 1.1.0)

radius_put_int — 整数属性を設定する

### 説明

function radius_put_int(
resource `$radius_handle`,
int `$type`,
int `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

整数属性を、現在の RADIUS リクエストにアタッチします。

> 注意: リクエストを radius_create_request() で作ってからでないと、この関数は呼べません。

### パラメータ

`radius_handle`
  RADIUS リソース。
`type`
  属性の型。
`value`
  属性の値。
`options`
  属性のオプションのビットマスク。使えるオプションには、`RADIUS_OPTION_TAGGED` や `RADIUS_OPTION_SALT` があります。
`tag`
  属性のタグ。`RADIUS_OPTION_TAGGED` が設定されていない限り、このパラメータは無視されます。

### 戻り値

成功した場合に `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_string

(PECL radius >= 1.1.0)

radius_put_string — 文字列属性を設定する

### 説明

function radius_put_string(
resource `$radius_handle`,
int `$type`,
string `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

文字列属性を、現在の RADIUS リクエストにアタッチします。 一般に、文字列属性をアタッチするには radius_put_attr() のほうがより便利です。 というのも、こちらのほうはバイナリセーフだからです。

> 注意: リクエストを radius_create_request() で作ってからでないと、この関数は呼べません。

### パラメータ

`radius_handle`
  RADIUS リソース。
`type`
  属性の型。
`value`
  属性の値。 これはヌル終端であることが期待されています。つまり、このパラメータはバイナリセーフではないということです。
`options`
  属性のオプションのビットマスク。使えるオプションには、`RADIUS_OPTION_TAGGED` や `RADIUS_OPTION_SALT` があります。
`tag`
  属性のタグ。`RADIUS_OPTION_TAGGED` が設定されていない限り、このパラメータは無視されます。

### 戻り値

成功した場合に `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() - ベンダー固有の文字列属性を設定する

# radius_put_vendor_addr

(PECL radius >= 1.1.0)

radius_put_vendor_addr — ベンダー固有の IP アドレス属性を設定する

### 説明

function radius_put_vendor_addr(
resource `$radius_handle`,
int `$vendor`,
int `$type`,
string `$addr`
): bool

ベンダー固有の IP アドレス属性を、現在の RADIUS リクエストにアタッチします。

> 注意: リクエストを radius_create_request() で作ってからでないと、この関数は呼べません。

### パラメータ

`radius_handle`
  RADIUS リソース。
`vendor`
  ベンダー ID。
`type`
  属性の型。
`addr`
  文字列形式の IPv4 アドレス。 `10.0.0.1` など。
`options`
  属性のオプションのビットマスク。使えるオプションには、`RADIUS_OPTION_TAGGED` や `RADIUS_OPTION_SALT` があります。
`tag`
  属性のタグ。`RADIUS_OPTION_TAGGED` が設定されていない限り、このパラメータは無視されます。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
PECL radius 1.3.0 | `options` および `tag` が追加されました。

# radius_put_vendor_attr

(PECL radius >= 1.1.0)

radius_put_vendor_attr — ベンダー固有のバイナリ属性を設定する

### 説明

function radius_put_vendor_attr(
resource `$radius_handle`,
int `$vendor`,
int `$type`,
string `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

ベンダー固有のバイナリ属性を、現在の RADIUS リクエストにアタッチします。

> 注意: リクエストを radius_create_request() で作ってからでないと、この関数は呼べません。

### パラメータ

`radius_handle`
  RADIUS リソース。
`vendor`
  ベンダー ID。
`type`
  属性の型。
`value`
  属性の値。バイナリ文字列として扱われます。
`options`
  属性のオプションのビットマスク。使えるオプションには、`RADIUS_OPTION_TAGGED` や `RADIUS_OPTION_SALT` があります。
`tag`
  属性のタグ。`RADIUS_OPTION_TAGGED` が設定されていない限り、このパラメータは無視されます。

### 戻り値

成功した場合に `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_int

(PECL radius >= 1.1.0)

radius_put_vendor_int — ベンダー固有の整数属性を設定する

### 説明

function radius_put_vendor_int(
resource `$radius_handle`,
int `$vendor`,
int `$type`,
int `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

ベンダー固有の整数属性を、現在の RADIUS リクエストにアタッチします。

> 注意: リクエストを radius_create_request() で作ってからでないと、この関数は呼べません。

### パラメータ

`radius_handle`
  RADIUS リソース。
`vendor`
  ベンダー ID。
`type`
  属性の型。
`value`
  属性の値。
`options`
  属性のオプションのビットマスク。使えるオプションには、`RADIUS_OPTION_TAGGED` や `RADIUS_OPTION_SALT` があります。
`tag`
  属性のタグ。`RADIUS_OPTION_TAGGED` が設定されていない限り、このパラメータは無視されます。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
PECL radius 1.3.0 | `options` および `tag` が追加されました。

### 参考

- radius_put_vendor_string() - ベンダー固有の文字列属性を設定する

# radius_put_vendor_string

(PECL radius >= 1.1.0)

radius_put_vendor_string — ベンダー固有の文字列属性を設定する

### 説明

function radius_put_vendor_string(
resource `$radius_handle`,
int `$vendor`,
int `$type`,
string `$value`,
int `$options` = 0,
int `$tag` = ?
): bool

ベンダー固有の文字列属性を、現在の RADIUS リクエストにアタッチします。 一般に、文字列属性をアタッチするには radius_put_vendor_attr() のほうがより便利です。 というのも、こちらのほうはバイナリセーフだからです。

> 注意: リクエストを radius_create_request() で作ってからでないと、この関数は呼べません。

### パラメータ

`radius_handle`
  RADIUS リソース。
`vendor`
  ベンダー ID。
`type`
  属性の型。
`value`
  属性の値。 これはヌル終端であることが期待されています。つまり、このパラメータはバイナリセーフではないということです。
`options`
  属性のオプションのビットマスク。使えるオプションには、`RADIUS_OPTION_TAGGED` や `RADIUS_OPTION_SALT` があります。
`tag`
  属性のタグ。`RADIUS_OPTION_TAGGED` が設定されていない限り、このパラメータは無視されます。

### 変更履歴

バージョン | 説明
--- | ---
PECL radius 1.3.0 | `options` および `tag` が追加されました。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- radius_put_vendor_int() - ベンダー固有の整数属性を設定する

# radius_request_authenticator

(PECL radius >= 1.1.0)

radius_request_authenticator — リクエスト認証子を返す

### 説明

function radius_request_authenticator(resource `$radius_handle`): string

パスワードや暗号化キーのような加工されたデータを復元する際には リクエスト認証子が必要となります。

### パラメータ

`radius_handle`
  RADIUS リソース。

### 戻り値

リクエスト認証子を文字列で返します。エラー時には `false` を返します。

### 参考

- radius_demangle() - データを復元する

# radius_salt_encrypt_attr

(PECL radius >= 1.3.0)

radius_salt_encrypt_attr — Salt-encrypts a value

### 説明

function 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_send_request

(PECL radius >= 1.1.0)

radius_send_request — リクエストを送信し、応答を待つ

### 説明

function radius_send_request(resource `$radius_handle`): int

Radius リクエストを作成した後は、 radius_send_request() でそれを送信します。

radius_send_request() 関数は、リクエストを送信して 応答を待ちます。定義されているサーバー間で、必要に応じてラウンドロビン 形式で再試行します。

### パラメータ

`radius_handle`
  RADIUS リソース。

### 戻り値

有効な応答を受信したら、radius_send_request() は応答の型を示す Radius コードを返します。一般的なコードは `RADIUS_ACCESS_ACCEPT`、 `RADIUS_ACCESS_REJECT` あるいは `RADIUS_ACCESS_CHALLENGE` です。 有効な応答を受信できなかった場合は、 radius_send_request() は `false` を返します。

### 参考

- radius_create_request() - 課金あるいは認証のリクエストを作成する

# radius_server_secret

(PECL radius >= 1.1.0)

radius_server_secret — 共有秘密鍵を返す

### 説明

function radius_server_secret(resource `$radius_handle`): string

パスワードや暗号化キーのような加工されたデータを復元する際の SALT として、共有秘密鍵が必要となります。

### パラメータ

`radius_handle`
  RADIUS リソース。

### 戻り値

サーバーの共有秘密鍵を文字列で返します。エラー時には `false` を返します。

# radius_strerror

(PECL radius >= 1.1.0)

radius_strerror — エラーメッセージを返す

### 説明

function radius_strerror(resource `$radius_handle`): string

Radius 関数が失敗した場合にはエラーメッセージが記録されます。 この関数により、エラーメッセージを取得することが可能となります。

### パラメータ

`radius_handle`
  RADIUS リソース。

### 戻り値

失敗した 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 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 — エラーメッセージを返す

- Radius
  - インストール/設定
  - 定義済み定数
  - 例
  - Radius 関数

# コマンドライン関連

# GNU Readline

# はじめに

readline 関数群は、GNU Readline ライブラリへの インターフェイスを実装したものです。これらの関数は、コマンドラインの 編集機能を提供します。一例をあげると、Bash において文字を挿入したり コマンド履歴を走査したりする際に、矢印キーを使用することを 可能にしているものです。 このライブラリは対話的なものであるため、Web アプリケーションで 使用されることはほとんどないでしょう。しかし、 コマンドライン から PHP を使用するスクリプトを書く際には有用です。

PHP 7.1.0 以降、この拡張モジュールは Windows でサポートされます。

警告

readline 拡張モジュールはスレッドセーフではありません！ (Apache の mod_winnt のような) 本物のスレッドセーフな SAPI と使わないことを強くお勧めします。

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定

## 要件

readline 関数を使用するには、libreadline ライブラリをインストールすることが 必要です。libreadline ライブラリは、 GNU Readline プロジェクトのホームページ » https://tiswww.case.edu/php/chet/readline/rltop.html からダウンロード可能です。 これは、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

(PHP 4, PHP 5, PHP 7, PHP 8)

readline — 一行読み込む

### 説明

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

# readline_add_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_add_history — ヒストリに 1 行追加する

### 説明

function readline_add_history(string `$prompt`): true

この関数は、コマンドラインヒストリに 1 行追加します。

### パラメータ

`prompt`
  ヒストリに追加する行。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | 戻り値の型が、`true` になりました。これより前のバージョンでは、bool でした。

# readline_callback_handler_install

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_handler_install — readline コールバックインターフェイスと端末を初期化し、 プロンプトを表示して結果をすぐに返す

### 説明

function readline_callback_handler_install(string `$prompt`, callable `$callback`): true

readline コールバックインターフェイスを設定し、プロンプト `prompt` を表示して入力を受け取ります。 コールバック関数 `callback` はひとつのパラメータを とり、そこにはユーザーの入力内容が格納されます。一度登録したコールバック インターフェイスを削除せずもういちどこの関数をコールした場合、もとの インターフェイスは自動的に上書きされます。

コールバック機能は stream_select() と組み合わせると 有用です。これは readline() とは異なり、 IO とユーザーの入力を交互に取り扱います。

### パラメータ

`prompt`
  確認メッセージ。
`callback`
  `callback` 関数が受け取るパラメータはひとつで、 ユーザーから返された入力です。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | 戻り値の型が、`true` になりました。これより前のバージョンでは、bool でした。

### 例

例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_remove

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_handler_remove — インストールされたハンドラを削除し、端末の設定をもとに戻す

### 説明

function readline_callback_handler_remove(): bool

インストールされたハンドラを削除し、端末の設定をもとに戻します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

インストールされたコールバックが削除できた場合に `true`、 削除するハンドラが見つからなかった場合に `false` を返します。

### 例

readline コールバックインターフェイスの使用方法についての例は readline_callback_handler_install() を参照ください。

### 参考

- readline_callback_handler_install() - readline コールバックインターフェイスと端末を初期化し、 プロンプトを表示して結果をすぐに返す
- readline_callback_read_char() - 文字を読み込み、改行を受け取ると readline コールバックインターフェイスに通知する

# readline_callback_read_char

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_callback_read_char — 文字を読み込み、改行を受け取ると readline コールバックインターフェイスに通知する

### 説明

function 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_clear_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_clear_history — ヒストリをクリアする

### 説明

function readline_clear_history(): true

この関数はコマンドラインヒストリ全体をクリアします。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | 戻り値の型が、`true` になりました。これより前のバージョンでは、bool でした。

# readline_completion_function

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_completion_function — 補完関数を登録する

### 説明

function readline_completion_function(callable `$callback`): bool

この関数は補完用の関数を登録します。 これは、Bash を使用している際に、タブキーを 押して得られるのと同様の機能です。

### パラメータ

`callback`
  コマンドラインの一部を入力とし、 マッチする可能性がある文字列の配列を返す 既存の関数の名前を指定する必要があります。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

# readline_info

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_info — 種々の readline の内部変数を取得/設定する

### 説明

function 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_list_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_list_history — ヒストリを一覧表示する

### 説明

function readline_list_history(): array

コマンドラインヒストリ全体を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

コマンドラインヒストリ全体の配列を返します。 各要素にはゼロから始まる整数の添字が付加されています。

# readline_on_new_line

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_on_new_line — カーソルが新しい行に移動したことを readline に通知する

### 説明

function readline_on_new_line(): void

readline に、カーソルが新しい行に移動したことを通知します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

値を返しません。

### 注意

> 注意: この関数は、依存する readline ライブラリがサポートしている場合にのみ利用できます。 この関数は、Windows ではサポートされていません。

# readline_read_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_read_history — ヒストリを読み込む

### 説明

function readline_read_history(?string `$filename` = `null`): bool

この関数は、コマンドヒストリをファイルから読み込みます。

### パラメータ

`filename`
  コマンドヒストリを含むファイルへのパス。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `filename` は、nullable になりました。

# readline_redisplay

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

readline_redisplay — 画面を再描画する

### 説明

function readline_redisplay(): void

画面の再描画を readline に依頼します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

値を返しません。

# readline_write_history

(PHP 4, PHP 5, PHP 7, PHP 8)

readline_write_history — ヒストリを書きこむ

### 説明

function readline_write_history(?string `$filename` = `null`): bool

この関数はコマンドヒストリをファイルに書き込みます。

### パラメータ

`filename`
  保存するファイルへのパス。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `filename` は、nullable になりました。

## 目次

- 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 — 一行読み込む
  - 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
  - インストール/設定
  - 定義済み定数
  - Readline 関数

# 圧縮およびアーカイブ

# Bzip2

# はじめに

bzip2関数は、bzip2 (.bz2) 圧縮されたファイルを透過的に読み書きするために使用します。

# インストール/設定

## 目次

- 要件
- インストール手順
- リソース型

## 要件

このモジュールは、Julian Seward により作成された » bzip2ライブラリの関数を使用しています。 このモジュールには、bzip2/libbzip2 のバージョン >= 1.0.x が必要です。

## インストール手順

PHP の bzip2 サポートはデフォルトでは有効となっていません。 bzip2 サポートを有効とするには、PHP をコンパイルする際に設定オプション --with-bz2[=DIR] を使用する必要があります。

## リソース型

この拡張モジュールは、リソース型として処理を行う bz2 ファイルを指すファイルポインタを定義します。

# 例

この例は、テンポラリファイルをオープンし、テスト用の文字列を書き込みます。 この後、このファイルの内容を出力します。

例1 簡単な bzip2 の例

    <?php

    $filename = "/tmp/testfile.bz2";
    $str = "This is a test string.\n";

    // 書き込み用にオープン
    $bz = bzopen($filename, "w");

    // ファイルに文字列を書き込む
    bzwrite($bz, $str);

    // ファイルを閉じる
    bzclose($bz);

    // 読み込み用にファイルをオープン
    $bz = bzopen($filename, "r");

    // 10文字読み込む
    echo bzread($bz, 10);

    // ファイルの終端まで出力(または次の1024文字)し、閉じる
    echo bzread($bz);

    bzclose($bz);

    ?>

# Bzip2 関数

# bzclose

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzclose — bzip2 ファイルを閉じる

### 説明

function bzclose(resource `$bz`): bool

与えられた bzip2 ファイルポインタを閉じます。

### パラメータ

`bz`
  ファイルポインタ。これは有効である必要があり、 bzopen() によりオープンされたファイルを指している必要があります。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- bzopen() - bzip2 圧縮されたファイルをオープンする

# bzcompress

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzcompress — 文字列をbzip2形式のデータに圧縮する

### 説明

function 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 形式のデータを解凍する

# bzdecompress

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzdecompress — bzip2 形式のデータを解凍する

### 説明

function 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形式のデータに圧縮する

# bzerrno

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerrno — bzip2 エラー番号を返す

### 説明

function bzerrno(resource `$bz`): int

与えられたファイルポインタから返された bzip2 エラーのエラー番号を返します。

### パラメータ

`bz`
  ファイルポインタ。これは有効である必要があり、 bzopen() によりオープンされたファイルを指してい る必要があります。

### 戻り値

整数としてのエラー番号を返します。

### 参考

- bzerror() - bzip2 エラー番号とエラー文字列を配列で返す
- bzerrstr() - bzip2 エラー文字列を返す

# bzerror

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerror — bzip2 エラー番号とエラー文字列を配列で返す

### 説明

function 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 エラー文字列を返す

# bzerrstr

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzerrstr — bzip2 エラー文字列を返す

### 説明

function bzerrstr(resource `$bz`): string

与えられたファイルポインタから返された bzip2 エラーのエラーの文字列を返します。

### パラメータ

`bz`
  ファイルポインタ。これは有効である必要があり、 bzopen() によりオープンされたファイルを指してい る必要があります。

### 戻り値

エラーメッセージを含む文字列を返します。

### 参考

- bzerrno() - bzip2 エラー番号を返す
- bzerror() - bzip2 エラー番号とエラー文字列を配列で返す

# bzflush

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzflush — 何もしない

### 説明

function bzflush(resource `$bz`): bool

バッファリングされた全ての bzip2 データをファイルポインタ `bz` に書き込むことが想定された関数です。 しかし、libbz2 では null な関数として実装されており、何もしません。

### パラメータ

`bz`
  ファイルポインタ。これは有効である必要があり、 bzopen() によりオープンされたファイルを指してい る必要があります。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- bzread() - バイナリ対応の bzip2 ファイル読み込み
- bzwrite() - バイナリ対応の bzip2 ファイルへの書き込み

# bzopen

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzopen — bzip2 圧縮されたファイルをオープンする

### 説明

function 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 ファイルを閉じる

# bzread

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzread — バイナリ対応の bzip2 ファイル読み込み

### 説明

function 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 圧縮されたファイルをオープンする

# bzwrite

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

bzwrite — バイナリ対応の bzip2 ファイルへの書き込み

### 説明

function 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 圧縮されたファイルをオープンする

## 目次

- bzclose — bzip2 ファイルを閉じる
- bzcompress — 文字列をbzip2形式のデータに圧縮する
- bzdecompress — bzip2 形式のデータを解凍する
- bzerrno — bzip2 エラー番号を返す
- bzerror — bzip2 エラー番号とエラー文字列を配列で返す
- bzerrstr — bzip2 エラー文字列を返す
- bzflush — 何もしない
- bzopen — bzip2 圧縮されたファイルをオープンする
- bzread — バイナリ対応の bzip2 ファイル読み込み
- bzwrite — バイナリ対応の bzip2 ファイルへの書き込み

- インストール/設定
  - 要件
  - インストール手順
  - リソース型
- 例
- Bzip2 関数
  - bzclose — bzip2 ファイルを閉じる
  - bzcompress — 文字列をbzip2形式のデータに圧縮する
  - bzdecompress — bzip2 形式のデータを解凍する
  - bzerrno — bzip2 エラー番号を返す
  - bzerror — bzip2 エラー番号とエラー文字列を配列で返す
  - bzerrstr — bzip2 エラー文字列を返す
  - bzflush — 何もしない
  - bzopen — bzip2 圧縮されたファイルをオープンする
  - bzread — バイナリ対応の bzip2 ファイル読み込み
  - bzwrite — バイナリ対応の bzip2 ファイルへの書き込み

# LZF

# はじめに

LZF は非常に高速な圧縮アルゴリズムで、わずかな速度の低下と引き換えに スペースを節約したい場合に適しています。 コンパイル時に速度もしくはスペースのどちらを優先して最適化を行うかを 選択することができます。この拡張モジュールは、Marc Lehmann による » liblzf ライブラリを用いて操作を行います。

# インストール/設定

## 目次

- インストール手順

## インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。 この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/lzf.

これらの関数を使用するには、--with-lzf[=DIR] オプションを指定して PHP を lzf サポートつきでコンパイルする必要があります。 --enable-lzf-better-compression を指定して、 圧縮速度より圧縮率を優先するよう LZF を設定することも可能です。

Windows ユーザーは、php.ini で php_lzf.dll を有効にすることでこれらの関数を使用可能です。

# LZF 関数

# lzf_compress

(PECL lzf >= 0.1.0)

lzf_compress — LZF 圧縮を行う

### 説明

function lzf_compress(string `$data`): string

lzf_compress() は、指定された `arg` を LZF 符号化方式で圧縮します。

### パラメータ

`data`
  圧縮するデータ。

### 戻り値

圧縮されたデータを返します。エラー時には `false` を返します。

### 参考

- lzf_decompress() - LZF 圧縮を伸長する

# lzf_decompress

(PECL lzf >= 0.1.0)

lzf_decompress — LZF 圧縮を伸長する

### 説明

function lzf_decompress(string `$data`): string

lzf_decompress() は、lzf で符号化された文字列を含む `data` を伸長します。

### パラメータ

`data`
  圧縮されたデータ。

### 戻り値

伸長したデータを返します。エラー時には `false` を返します。

### 参考

- lzf_compress() - LZF 圧縮を行う

# lzf_optimized_for

(PECL lzf >= 1.0.0)

lzf_optimized_for — LZF 拡張モジュールの最適化指定を取得する

### 説明

function lzf_optimized_for(): int

LZF 拡張モジュールが圧縮時に使用した最適化指定を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

LZF が速度に最適化されている場合に 1、圧縮率に最適化されている場合に 0 を返します。

## 目次

- lzf_compress — LZF 圧縮を行う
- lzf_decompress — LZF 圧縮を伸長する
- lzf_optimized_for — LZF 拡張モジュールの最適化指定を取得する

- インストール/設定
  - インストール手順
- LZF 関数
  - lzf_compress — LZF 圧縮を行う
  - lzf_decompress — LZF 圧縮を伸長する
  - lzf_optimized_for — LZF 拡張モジュールの最適化指定を取得する

# Phar

# はじめに

phar 拡張モジュールは、PHP アプリケーション全体をひとつの "phar" (PHP Archive) ファイルにまとめてしまい、配布やインストールを容易にするためのものです。 それだけでなく、phar 拡張モジュールではファイルフォーマットを抽象化する機能も提供しており、 tar 形式や zip 形式のファイルを PharData クラスで扱うことができます。ちょうど PDO がさまざまなデータベースへの統一インターフェイスを用意しているのと同じようなものです。 PDO では異なるデータベース間の変換はできませんが、 phar では tar、zip、phar ファイルフォーマット間の変換がコード 1 行だけでできてしまいます。 例として Phar::convertToExecutable() を参照ください。

Phar って何? Phar アーカイブは、複数のファイルをひとつにまとめるための便利な仕組みです。 Phar アーカイブを使用すれば、PHP のアプリケーションをひとつのファイルとして配布できるようになります。 また、それをディスク上に展開しなくてもそのまま実行できるのです。 さらに、他のファイルと同様に PHP から phar アーカイブを実行することができます。 コマンドラインとウェブサーバー経由のどちらでも実行可能です。 phar は、いわば PHP アプリケーションにおける thumb drive のようなものです。

Phar はこの機能を実装するために ストリームラッパー を使用しています。通常は、PHP スクリプトから外部のファイルを使用するには include を用います。

例1 外部ファイルの使用

    <?php
     include '/path/to/external/file.php';
     ?>

PHP は、実際には `/path/to/external/file.php` をストリームラッパー `file:///path/to/external/file.php` とみなし、 内部的にはファイルストリームラッパーのストリーム関数でローカルファイルにアクセスしています。

Phar アーカイブ `/path/to/myphar.phar` の中に含まれるファイル `file.php` を使用する場合に構文は、 先ほどの `file://` 構文と似ています。

例2 Phar アーカイブ内のファイルの使用

    <?php
     include 'phar:///path/to/myphar.phar/file.php';
     ?>

実際のところ、phar アーカイブは外部ディスクと同様に扱うことができます。 fopen() 系の関数や opendir()、そして mkdir() 系の関数を使用して、 phar アーカイブ内のファイルの読み書きや新しいファイルの作成が可能です。 これにより、完全な PHP アプリケーションを単一のファイルで配布して そのままの形式で直接実行できるようになるのです。

Phar アーカイブのもっとも一般的な使用法は、 完全なアプリケーションをひとつのファイルにまとめて配布することです。 たとえば、PHP に同梱されている PEAR インストーラは phar アーカイブとして配布されています。 このような形式の phar アーカイブを使用するには、 コマンドラインあるいはウェブサーバーからアーカイブを実行します。

Phar アーカイブの配布形式は `tar` アーカイブか `zip` アーカイブ、あるいは専用の `phar` 独自ファイルフォーマットのいずれかとなります。 それぞれの形式には利点と欠点があります。 tar 形式や zip 形式は、他のツールからでも内容を読んだり展開したりできるという利点がありますが、 それを実行する環境にも phar 拡張モジュールが必要となります。 phar 独自フォーマットは phar 拡張モジュール独自の形式です。 phar 拡張モジュールか PEAR パッケージ » PHP_Archive にしか作成できません。しかし、この形式で作成したアプリケーションは phar 拡張モジュールのない環境でも動作するという利点があります。

言い換えると、phar 拡張モジュールが無効になっている環境でも phar アーカイブを実行できるということです。 しかし、phar アーカイブ内の個別のファイルにアクセスするには、 (PHP_Archive で作成したものでない限り) phar 拡張モジュールが必要です。

phar 拡張モジュールには、tar ファイルを zip 形式や phar 形式に変換する機能もあります。

例3 phar 形式から tar 形式への phar アーカイブの変換

    <?php
     $phar = new Phar('myphar.phar');
     $pgz = $phar->convertToExecutable(Phar::TAR, Phar::GZ); // myphar.phar.tar.gz を作成します
     ?>

phar には、特定のファイルあるいはアーカイブ全体を gzip あるいは bzip2 で圧縮する機能があります。 また、アーカイブの整合性を MD5、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 アーカイブは、 動かす前に多少手を入れなければならないことがよくあります。

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定
- リソース型

## 要件

オプションとして、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 アーカイブの作成: 導入

## 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 function __construct(string `$filename`, int `$flags` = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS, ?string `$alias` = `null`)
public function addEmptyDir(string `$directory`): void
public function addFile(string `$filename`, ?string `$localName` = `null`): void
public function addFromString(string `$localName`, string `$contents`): void
final public static function apiVersion(): string
public function buildFromDirectory(string `$directory`, string `$pattern` = ""): array
public function buildFromIterator(Traversable `$iterator`, ?string `$baseDirectory` = `null`): array
final public static function canCompress(int `$compression` = 0): bool
final public static function canWrite(): bool
public function compress(int `$compression`, ?string `$extension` = `null`): ?Phar
public function compressFiles(int `$compression`): void
public function convertToData(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?PharData
public function convertToExecutable(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?Phar
public function copy(string `$from`, string `$to`): true
public function count(int `$mode` = `COUNT_NORMAL`): int
final public static function createDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): string
public function decompress(?string `$extension` = `null`): ?Phar
public function decompressFiles(): true
public function delMetadata(): true
public function delete(string `$localName`): true
public function extractTo(string `$directory`, array|string|null `$files` = `null`, bool `$overwrite` = `false`): bool
public function getAlias(): ?string
public function getMetadata(array `$unserializeOptions` = []): mixed
public function getModified(): bool
public function getPath(): string
public function getSignature(): array|false
public function getStub(): string
final public static function getSupportedCompression(): array
final public static function getSupportedSignatures(): array
public function getVersion(): string
public function hasMetadata(): bool
final public static function interceptFileFuncs(): void
public function isBuffering(): bool
public function isCompressed(): int|false
public function isFileFormat(int `$format`): bool
final public static function isValidPharFilename(string `$filename`, bool `$executable` = `true`): bool
public function isWritable(): bool
final public static function loadPhar(string `$filename`, ?string `$alias` = `null`): bool
final public static function mapPhar(?string `$alias` = `null`, int `$offset` = 0): bool
final public static function mount(string `$pharPath`, string `$externalPath`): void
final public static function mungServer(array `$variables`): void
public function offsetExists(string `$localName`): bool
public function offsetGet(string `$localName`): SplFileInfo
public function offsetSet(string `$localName`, resource|string `$value`): void
public function offsetUnset(string `$localName`): void
final public static function running(bool `$returnPhar` = `true`): string
public function setAlias(string `$alias`): true
public function setDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): true
public function setMetadata(mixed `$metadata`): void
public function setSignatureAlgorithm(int `$algo`, ?string `$privateKey` = `null`): void
public function setStub(resource|string `$stub`, int `$length` = -1): true
public function startBuffering(): void
public function stopBuffering(): void
final public static function unlinkArchive(string `$filename`): true
final public static function webPhar(
?string `$alias` = `null`,
?string `$index` = `null`,
?string `$fileNotFoundScript` = `null`,
array `$mimeTypes` = [],
?callable `$rewrite` = `null`
): void
public function __destruct()
/* 継承したメソッド */
public function RecursiveDirectoryIterator::getChildren(): RecursiveDirectoryIterator
public function RecursiveDirectoryIterator::getSubPath(): string
public function RecursiveDirectoryIterator::getSubPathname(): string
public function RecursiveDirectoryIterator::hasChildren(bool `$allowLinks` = `false`): bool
public function RecursiveDirectoryIterator::key(): string
public function RecursiveDirectoryIterator::next(): void
public function RecursiveDirectoryIterator::rewind(): void
public function FilesystemIterator::current(): string|SplFileInfo|FilesystemIterator
public function FilesystemIterator::getFlags(): int
public function FilesystemIterator::key(): string
public function FilesystemIterator::next(): void
public function FilesystemIterator::rewind(): void
public function FilesystemIterator::setFlags(int `$flags`): void
public function DirectoryIterator::current(): mixed
public function DirectoryIterator::getBasename(string `$suffix` = ""): string
public function DirectoryIterator::getExtension(): string
public function DirectoryIterator::getFilename(): string
public function DirectoryIterator::isDot(): bool
public function DirectoryIterator::key(): mixed
public function DirectoryIterator::next(): void
public function DirectoryIterator::rewind(): void
public function DirectoryIterator::seek(int `$offset`): void
public function DirectoryIterator::__toString(): string
public function DirectoryIterator::valid(): bool
public function SplFileInfo::getATime(): int|false
public function SplFileInfo::getBasename(string `$suffix` = ""): string
public function SplFileInfo::getCTime(): int|false
public function SplFileInfo::getExtension(): string
public function SplFileInfo::getFileInfo(?string `$class` = `null`): SplFileInfo
public function SplFileInfo::getFilename(): string
public function SplFileInfo::getGroup(): int|false
public function SplFileInfo::getInode(): int|false
public function SplFileInfo::getLinkTarget(): string|false
public function SplFileInfo::getMTime(): int|false
public function SplFileInfo::getOwner(): int|false
public function SplFileInfo::getPath(): string
public function SplFileInfo::getPathInfo(?string `$class` = `null`): ?SplFileInfo
public function SplFileInfo::getPathname(): string
public function SplFileInfo::getPerms(): int|false
public function SplFileInfo::getRealPath(): string|false
public function SplFileInfo::getSize(): int|false
public function SplFileInfo::getType(): string|false
public function SplFileInfo::isDir(): bool
public function SplFileInfo::isExecutable(): bool
public function SplFileInfo::isFile(): bool
public function SplFileInfo::isLink(): bool
public function SplFileInfo::isReadable(): bool
public function SplFileInfo::isWritable(): bool
public function SplFileInfo::openFile(string `$mode` = "r", bool `$useIncludePath` = `false`, ?resource `$context` = `null`): SplFileObject
public function SplFileInfo::setFileClass(string `$class` = `SplFileObject::class`): void
public function SplFileInfo::setInfoClass(string `$class` = `SplFileInfo::class`): void
public function SplFileInfo::__toString(): string
}

## 変更履歴

バージョン | 説明
--- | ---
8.4.0 | Zip アーカイブの Unix タイムスタンプ拡張のサポートが追加されました。
8.0.0 | アーカイブをオープンした際に、メタデータは展開されなくなりました。 展開処理は、Phar::getMetadata() をコールするまで遅延されます。

## 注意

警告

PHP 8.0.0 より前のバージョンでは、アーカイブをオープンした際に、 メタデータが展開されていました。このことで、 セキュリティ上の脆弱性に繋がる可能性がありました。 PHP 8.0.0 移行では、メタデータは Phar::getMetadata() をコールした時にのみ展開されるようになりました。 このメソッドには、セキュリティ上の理由で、 展開を制限するオプションが存在します。

# Phar::addEmptyDir

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addEmptyDir — 空のディレクトリを phar アーカイブに追加する

### 説明

public function 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::addFile

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addFile — ファイルシステム上のファイルを phar アーカイブに追加する

### 説明

public function 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::addFromString

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::addFromString — 文字列から、ファイルを phar アーカイブに追加する

### 説明

public function 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 アーカイブに追加する

# Phar::apiVersion

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::apiVersion — API のバージョンを返す

### 説明

final public static function 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::buildFromDirectory

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::buildFromDirectory — ディレクトリ内のファイルから phar を作成する

### 説明

public function 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::buildFromIterator

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::buildFromIterator — イテレータから phar アーカイブを作成する

### 説明

public function 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::canCompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::canCompress — phar 拡張モジュールが zlib あるいは bzip2 による圧縮をサポートしているかどうかを返す

### 説明

final public static function 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::canWrite

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::canWrite — phar 拡張モジュールが phar の書き込みや作成をサポートしているかどうかを返す

### 説明

final public static function 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::compress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::compress — Phar アーカイブ全体を Gzip あるいは Bzip2 で圧縮する

### 説明

public function 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::compressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::compressFiles — 現在の Phar アーカイブ内のすべてのファイルを圧縮する

### 説明

public function 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::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::__construct — Phar アーカイブオブジェクトを作成する

### 説明

public function 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::convertToData

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::convertToData — phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する

### 説明

public function 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::convertToExecutable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::convertToExecutable — phar アーカイブを実行可能な別の phar アーカイブ形式に変換する

### 説明

public function 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::copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::copy — phar アーカイブ内のファイルを、phar 内で別の新しいファイルとしてコピーする

### 説明

public function Phar::copy(string `$from`, string `$to`): true

> 注意: このメソッドは、php.ini の `phar.readonly` が `0` でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

phar アーカイブ内のファイルを、そのアーカイブ内で別の新しいファイルとしてコピーします。 これは、phar ストリームラッパーでの copy() と同等の操作をオブジェクト指向で行うものです。

### パラメータ

`from`

`to`

### 戻り値

常に `true` を返します。

### エラー / 例外

コピー元のファイルが存在しない、コピー先のファイルが既に存在する、 書き込みアクセスが無効になっている、どちらかのファイルのオープンに失敗した、 あるいはコピー元のファイルの読み込みに失敗した場合に 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']; // 出力は "phar://myphar.phar/b"
    } catch (Exception $e) {
        // エラー処理
    }

    // 上のコードと同等の処理をストリームラッパーで行う例。
    // エラー時には例外ではなく E_WARNINGS が発生します
    copy('phar://myphar.phar/a', 'phar//myphar.phar/c');
    echo file_get_contents('phar://myphar.phar/c'); // 出力は "hi"

    ?>

# Phar::count

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::count — Phar アーカイブ内のエントリ (ファイル) の数を返す

### 説明

public function 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::createDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::createDefaultStub — phar ファイルフォーマット用のスタブを作成する

### 説明

final public static function 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::decompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::decompress — Phar アーカイブ全体の圧縮を解除する

### 説明

public function 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::decompressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::decompressFiles — 現在の Phar アーカイブ内のすべてのファイルの圧縮を解除する

### 説明

public function Phar::decompressFiles(): true

> 注意: このメソッドは、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` を返します。

### エラー / 例外

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::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::delMetadata — phar のグローバルメタデータを削除する

### 説明

public function Phar::delMetadata(): true

> 注意: このメソッドは、php.ini の `phar.readonly` が `0` でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

phar のグローバルメタデータを削除します。

### パラメータ

### 戻り値

常に `true` を返します。

### エラー / 例外

変更をディスクに書き戻す際にエラーが発生した場合は 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::delete

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::delete — phar アーカイブ内のファイルを削除する

### 説明

public function Phar::delete(string `$localName`): true

> 注意: このメソッドは、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::__destruct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::__destruct — アクティブな Phar オブジェクトを破棄する

### 説明

public function Phar::__destruct()

### パラメータ

この関数にはパラメータはありません。

# Phar::extractTo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::extractTo — phar アーカイブの内容をディレクトリに展開する

### 説明

public function 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::getAlias

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.1)

Phar::getAlias — Phar のエイリアスを取得する

### 説明

public function Phar::getAlias(): ?string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

エイリアスを返します。エイリアスがない場合は `null` を返します。

# Phar::getMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getMetadata — phar アーカイブのメタデータを返す

### 説明

public function Phar::getMetadata(array `$unserializeOptions` = []): mixed

アーカイブのメタデータを取得します。メタデータは、PHP の任意の変数をシリアライズしたものです。

警告

メタデータにアクセスすると、メタデータの展開処理が発生します。 これによって、任意の PHP コードの実行をトリガできます。 このメソッドを信頼できない phar アーカイブに対して使ってはいけません。 使う場合は、`unserializeOptions` を安全な方法で設定してください。

### パラメータ

パラメータはありません。

### 戻り値

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::getModified

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getModified — phar が変更されているかどうかを返す

### 説明

public function Phar::getModified(): bool

このメソッドを使用すると、phar 内のファイルが 削除されたり変更されたりしているかどうかを判断できます。

### パラメータ

パラメータはありません。

### 戻り値

オープンした後でファイルが変更されている場合に `true`、 そうでない場合に `false` を返します。

# Phar::getPath

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

Phar::getPath — Pharアーカイブのディスク上の実際のパスを取得する

### 説明

public function Phar::getPath(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# 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 function 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::getStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getStub — Phar アーカイブの PHP ローダーあるいは起動スタブを返す

### 説明

public function 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::getSupportedCompression

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::getSupportedCompression — サポートする圧縮アルゴリズムの配列を返す

### 説明

final public static function 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::getSupportedSignatures

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.1.0)

Phar::getSupportedSignatures — サポートするシグネチャ型の配列を返す

### 説明

final public static function Phar::getSupportedSignatures(): array

サポートするシグネチャ型の配列を返します。

### パラメータ

パラメータはありません。

### 戻り値

`MD5`、`SHA-1`、 `SHA-256`、`SHA-512` あるいは `OpenSSL` を含む配列を返します。

### 参考

- Phar::getSignature() - Phar アーカイブの MD5/SHA1/SHA256/SHA512/OpenSSL シグネチャを返す
- Phar::setSignatureAlgorithm() - phar のシグネチャのアルゴリズムを設定して適用する

# Phar::getVersion

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::getVersion — Phar アーカイブのバージョン情報を返す

### 説明

public function Phar::getVersion(): string

オープンした Phar アーカイブの API バージョンを返します。

### パラメータ

### 戻り値

オープンしたアーカイブの API バージョンを返します。 これは、読み込んだ phar 拡張モジュールが新しい phar を作成する際に使用する API バージョンとは異なります。各 Phar アーカイブは、 マニフェスト内に API バージョンをハードコードして保持しています。 詳細は Phar ファイルフォーマット のドキュメントを参照ください。

### 参考

- Phar::apiVersion() - API のバージョンを返す

# Phar::hasMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::hasMetadata — ファイルがグローバルなメタデータを持つかどうかを返す

### 説明

public function 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 のグローバルメタデータを削除する

# 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 function Phar::interceptFileFuncs(): void

fopen() や readfile()、 file_get_contents()、opendir() などの stat 関連の関数をすべて phar に横取りさせます。 phar アーカイブ内で相対パスを指定してこれらの関数がコールされると、 それが phar アーカイブ内のファイルへのアクセスに変更されます。 絶対パスの場合は、ファイルシステム上の外部ファイルを指すものとみなされます。

この関数を使用すると、ハードディスク上で動作するように作られている PHP アプリケーションを phar アプリケーションにまとめられるようになります。

### パラメータ

パラメータはありません。

### 戻り値

### 例

例1 Phar::interceptFileFuncs() の例

    <?php
    Phar::interceptFileFuncs();
    include 'phar://' . __FILE__ . '/file.php';
    ?>

phar ファイルの場所が `/path/to/myphar.phar` で、その中に `file.php` と `file2.txt` が存在するものとします。 `file.php` にこのようなコードが含まれていた場合、

例2 Phar::interceptFileFuncs() の例

    <?php
    echo file_get_contents('file2.txt');
    ?>

通常は、PHP はカレントディレクトリの `file2.txt` を探します。カレントディレクトリの場所は、file.php と同じ場所かあるいは コマンドラインで実行した際のカレントディレクトリとなります。 Phar::interceptFileFuncs() を使用した場合は、 PHP はカレントディレクトリを `phar:///path/to/myphar.phar/` とみなし、上のコードの場合は `phar:///path/to/myphar.phar/file2.txt` をオープンします。

# Phar::isBuffering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::isBuffering — Phar の書き込み操作がバッファリングされるか、あるいは直接ディスクに書き込まれるかを調べる

### 説明

public function 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::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 function 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::isFileFormat

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::isFileFormat — phar アーカイブが、パラメータで指定した tar/phar/zip のいずれかの形式である場合に true を返す

### 説明

public function 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::isValidPharFilename

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

Phar::isValidPharFilename — 指定したファイル名が正しい形式の phar ファイルかどうかを返す

### 説明

final public static function Phar::isValidPharFilename(string `$filename`, bool `$executable` = `true`): bool

指定したファイル名のファイルが、phar 拡張モジュールで利用できる 正しい形式の phar ファイルであるかどうかを返します。 これは、phar アーカイブを実際に開く前にそのファイルを確認する際に使用します。 これで、 無効なファイルを指定したときに当然発生するであろう例外の処理を省略することができます。

### パラメータ

`filename`

  まだ作成されていない phar アーカイブの名前あるいはフルパス。

`executable`

  このパラメータは、指定した名前のファイルを phar の実行可能アーカイブとして扱うかデータのみの非実行可能アーカイブとして扱うかを指定します。

### 戻り値

正しい形式のファイルである場合に `true`、そうでない場合に `false` を返します。

# Phar::isWritable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::isWritable — phar アーカイブが変更可能な場合に true を返す

### 説明

public function Phar::isWritable(): bool

このメソッドは、`phar.readonly` が `0` かつディスク上の実際の phar アーカイブが読み取り専用でない場合に `true` を返します。

### パラメータ

パラメータはありません。

### 戻り値

phar アーカイブが変更可能な場合に `true` を返します。

### 参考

- Phar::canWrite() - phar 拡張モジュールが phar の書き込みや作成をサポートしているかどうかを返す
- PharData::isWritable() - tar/zip アーカイブが変更可能な場合に true を返す

# Phar::loadPhar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::loadPhar — 任意の phar アーカイブを、エイリアスを指定して読み込む

### 説明

final public static function 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::mapPhar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::mapPhar — 現在実行されている (phar 形式の) ファイルを読み込み、その内容を登録する

### 説明

final public static function 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::mount

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::mount — 外部のパスあるいはファイルを phar アーカイブ内に仮想的にマウントする

### 説明

final public static function 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';
    ?>

# Phar::mungServer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::mungServer — 最大 4 つまでの $_SERVER 変数を実行時に変更させる

### 説明

final public static function 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::offsetExists

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetExists — ファイルが phar 内に存在するかどうかを調べる

### 説明

public function 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 から削除する

# Phar::offsetGet

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetGet — 指定したファイルの PharFileInfo オブジェクトを取得する

### 説明

public function 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::offsetSet

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetSet — 内部ファイルに、外部ファイルの内容を設定する

### 説明

public function 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::offsetUnset

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::offsetUnset — ファイルを phar から削除する

### 説明

public function 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::running

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::running — 現在実行中の Phar アーカイブのフルパスあるいは完全な phar URL を返す

### 説明

final public static function 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::setAlias

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.1)

Phar::setAlias — Phar アーカイブのエイリアスを設定する

### 説明

public function Phar::setAlias(string `$alias`): true

> 注意: このメソッドは、php.ini の `phar.readonly` が `0` でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

Phar アーカイブのエイリアスを設定し、そのアーカイブのエイリアスとして書き込みます。 エイリアスは phar アーカイブで内部的に使用するもので、 `phar` ストリームラッパーがアーカイブ内のファイルにアクセスする際に そのアーカイブのファイルシステム上での場所を気にせずにすむようになります。 それ以外の方法としては、Phar が内部的に include を横取りすることを利用したり Phar::interceptFileFuncs() を使って相対パスを利用したりといったものがあります。

### パラメータ

`alias`

  このアーカイブを指すときに使用する短い文字列。 `phar` ストリームラッパーがアクセスする際にこれを使用します。

### 戻り値

常に `true` を返します。

### エラー / 例外

書き込みアクセスが無効となっている場合に UnexpectedValueException をスローします。 また、そのエイリアスが既に使用済みである場合や 変更をディスクに書き込むときにエラーが発生した場合は PharException をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | Phar::setAlias() の 仮の戻り値の型が、true になりました。

### 例

例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::setDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::setDefaultStub — Phar アーカイブの PHP ローダー (起動スタブ) をデフォルトのローダーに設定する

### 説明

public function Phar::setDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): true

> 注意: このメソッドは、php.ini の `phar.readonly` が `0` でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

このメソッドは、 Phar::createDefaultStub() と Phar::setStub() の両方の機能を組み合わせた便利なメソッドです。

### パラメータ

`index`

  コマンドラインからアクセスした場合に実行する、 phar アーカイブ内の相対パス。

`webIndex`

  ウェブブラウザからアクセスした場合に実行する、 phar アーカイブ内の相対パス。

### 戻り値

常に `true` を返します。

### エラー / 例外

phar.readonly が php.ini で有効になっている場合に UnexpectedValueException をスローします。 変更内容をディスクに書き込む際にエラーが発生した場合は PharException をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | Phar::setDefaultStub() の 仮の戻り値の型が、true になりました。
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::setMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::setMetadata — phar アーカイブのメタデータを設定する

### 説明

public function 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::setSignatureAlgorithm

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.1.0)

Phar::setSignatureAlgorithm — phar のシグネチャのアルゴリズムを設定して適用する

### 説明

public function 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::setStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::setStub — Phar アーカイブの PHP ローダ (あるいは起動スタブ) を設定する

### 説明

public function Phar::setStub(resource|string `$stub`, int `$length` = -1): true

> 注意: このメソッドは、php.ini の `phar.readonly` が `0` でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

このメソッドを使用して、新しい Phar アーカイブに PHP 起動ローダスタブを追加します。あるいは、既存の Phar アーカイブのローダスタブを置き換えます。

Phar アーカイブのローダスタブは、 このようにアーカイブを直接インクルードした際に使用されます。

    <?php
    include 'myphar.phar';
    ?>

あるいは、単にこのように実行した際にも使用されます。

    php myphar.phar

`phar` ストリームラッパーを使用して次のようにファイルをインクルードした際には、 ローダにはアクセスしません。

    <?php
    include 'phar://myphar.phar/somefile.php';
    ?>

### パラメータ

`stub`

  文字列あるいはオープンしたストリームハンドル。 この phar アーカイブの実行スタブとして使用します。

`length`
  `stub` の長さ（バイト単位）。
  警告

  第一引数に resource を指定して `length` 引数を渡すことは、 PHP 8.3.0 以降では非推奨です。 かわりに `$phar->setStub(stream_get_contents($resource))` を使ってください。

### 戻り値

常に `true` を返します。

### エラー / 例外

php.ini で phar.readonly が有効になっている場合に UnexpectedValueException がスローされます。 変更をディスクに書き込む際に何らかの問題が発生した場合は PharException がスローされます。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 戻り値の型が、`true` になりました。これより前のバージョンでは、bool でした。
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(); ?>"

### 参考

- Phar::getStub() - Phar アーカイブの PHP ローダーあるいは起動スタブを返す
- Phar::createDefaultStub() - phar ファイルフォーマット用のスタブを作成する

# Phar::startBuffering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::startBuffering — Phar の書き込み操作のバッファリングを開始するが、ディスク上の Phar オブジェクトは変更しない

### 説明

public function Phar::startBuffering(): void

技術的には必須ではありませんが、Phar::startBuffering() メソッドを使用すると、大量のファイルを含む Phar アーカイブの作成や変更が非常に高速になります。 通常は、Phar アーカイブ内のファイルが作成あるいは変更されるたびに Phar アーカイブ全体を改めて作り直します。 これによって、アーカイブが常に最新の状態となります。

しかし、単に新しい Phar アーカイブを作りたいときや アーカイブ全体を一度に書き出したいときなどは、これは不要です。 同様に、いくつかの変更を行うときに、 すべての変更がうまくいったことを確認してから実際にディスクに書き込みたい ということもあるでしょう。 これは、ちょうどデータベースのトランザクションの概念と同じようなものです。 Phar::startBuffering()/Phar::stopBuffering() の両メソッドが、このような場合のために用意されています。

Phar の書き込みバッファリングはアーカイブ単位で処理されます。 Phar アーカイブ `foo.phar` でバッファリングが有効であったとしても、それは Phar アーカイブ `bar.phar` の変更には影響しません。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

値を返しません。

### 例

例1 Phar::startBuffering() の例

    <?php
    // 確実に消しておきます
    @unlink('brandnewphar.phar');
    try {
        $p = new Phar(dirname(__FILE__) . '/brandnewphar.phar', 0, 'brandnewphar.phar');
    } catch (Exception $e) {
        echo 'phar を作成できません:', $e;
    }
    echo '新しい phar のエントリ数は ' . $p->count() . " です\n";
    $p->startBuffering();
    $p['file.txt'] = 'hi';
    $p['file2.txt'] = 'there';
    $p['file2.txt']->setCompressedGZ();
    $p['file3.txt'] = 'babyface';
    $p['file3.txt']->setMetadata(42);
    $p->setStub("<?php
    function __autoload($class)
    {
        include 'phar://myphar.phar/' . str_replace('_', '/', $class) . '.php';
    }
    Phar::mapPhar('myphar.phar');
    include 'phar://myphar.phar/startup.php';
    __HALT_COMPILER();");
    $p->stopBuffering();
    ?>

### 参考

- Phar::stopBuffering() - Phar アーカイブへの書き込みリクエストのバッファリングを終了し、変更内容をディスクに書き込む
- Phar::isBuffering() - Phar の書き込み操作がバッファリングされるか、あるいは直接ディスクに書き込まれるかを調べる

# Phar::stopBuffering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

Phar::stopBuffering — Phar アーカイブへの書き込みリクエストのバッファリングを終了し、変更内容をディスクに書き込む

### 説明

public function 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::unlinkArchive

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::unlinkArchive — phar アーカイブをディスクとメモリから完全に削除する

### 説明

final public static function Phar::unlinkArchive(string `$filename`): true

phar アーカイブをディスクとメモリから削除します。

### パラメータ

`filename`

  ディスク上の phar アーカイブへのパス。

### 戻り値

常に `true` を返します。

### エラー / 例外

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::webPhar

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

Phar::webPhar — ブラウザからのリクエストを、phar アーカイブ内部のファイルに転送する

### 説明

final public static function 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 に横取りさせる

## 目次

- 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 クラス

(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 function __construct(
string `$filename`,
int `$flags` = FilesystemIterator::SKIP_DOTS | FilesystemIterator::UNIX_PATHS,
?string `$alias` = `null`,
int `$format` = 0
)
public function addEmptyDir(string `$directory`): void
public function addFile(string `$filename`, ?string `$localName` = `null`): void
public function addFromString(string `$localName`, string `$contents`): void
public function buildFromDirectory(string `$directory`, string `$pattern` = ""): array
public function buildFromIterator(Traversable `$iterator`, ?string `$baseDirectory` = `null`): array
public function compress(int `$compression`, ?string `$extension` = `null`): ?PharData
public function compressFiles(int `$compression`): void
public function convertToData(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?PharData
public function convertToExecutable(?int `$format` = `null`, ?int `$compression` = `null`, ?string `$extension` = `null`): ?Phar
public function copy(string `$from`, string `$to`): true
public function decompress(?string `$extension` = `null`): ?PharData
public function decompressFiles(): true
public function delMetadata(): true
public function delete(string `$localName`): true
public function extractTo(string `$directory`, array|string|null `$files` = `null`, bool `$overwrite` = `false`): bool
public function isWritable(): bool
public function offsetSet(string `$localName`, resource|string `$value`): void
public function offsetUnset(string `$localName`): void
public function setAlias(string `$alias`): bool
public function setDefaultStub(?string `$index` = `null`, ?string `$webIndex` = `null`): bool
public function setMetadata(mixed `$metadata`): void
public function setSignatureAlgorithm(int `$algo`, ?string `$privateKey` = `null`): void
public function setStub(resource|string `$stub`, int `$length` = -1): true
public function __destruct()
/* 継承したメソッド */
public function RecursiveDirectoryIterator::getChildren(): RecursiveDirectoryIterator
public function RecursiveDirectoryIterator::getSubPath(): string
public function RecursiveDirectoryIterator::getSubPathname(): string
public function RecursiveDirectoryIterator::hasChildren(bool `$allowLinks` = `false`): bool
public function RecursiveDirectoryIterator::key(): string
public function RecursiveDirectoryIterator::next(): void
public function RecursiveDirectoryIterator::rewind(): void
public function FilesystemIterator::current(): string|SplFileInfo|FilesystemIterator
public function FilesystemIterator::getFlags(): int
public function FilesystemIterator::key(): string
public function FilesystemIterator::next(): void
public function FilesystemIterator::rewind(): void
public function FilesystemIterator::setFlags(int `$flags`): void
public function DirectoryIterator::current(): mixed
public function DirectoryIterator::getBasename(string `$suffix` = ""): string
public function DirectoryIterator::getExtension(): string
public function DirectoryIterator::getFilename(): string
public function DirectoryIterator::isDot(): bool
public function DirectoryIterator::key(): mixed
public function DirectoryIterator::next(): void
public function DirectoryIterator::rewind(): void
public function DirectoryIterator::seek(int `$offset`): void
public function DirectoryIterator::__toString(): string
public function DirectoryIterator::valid(): bool
public function SplFileInfo::getATime(): int|false
public function SplFileInfo::getBasename(string `$suffix` = ""): string
public function SplFileInfo::getCTime(): int|false
public function SplFileInfo::getExtension(): string
public function SplFileInfo::getFileInfo(?string `$class` = `null`): SplFileInfo
public function SplFileInfo::getFilename(): string
public function SplFileInfo::getGroup(): int|false
public function SplFileInfo::getInode(): int|false
public function SplFileInfo::getLinkTarget(): string|false
public function SplFileInfo::getMTime(): int|false
public function SplFileInfo::getOwner(): int|false
public function SplFileInfo::getPath(): string
public function SplFileInfo::getPathInfo(?string `$class` = `null`): ?SplFileInfo
public function SplFileInfo::getPathname(): string
public function SplFileInfo::getPerms(): int|false
public function SplFileInfo::getRealPath(): string|false
public function SplFileInfo::getSize(): int|false
public function SplFileInfo::getType(): string|false
public function SplFileInfo::isDir(): bool
public function SplFileInfo::isExecutable(): bool
public function SplFileInfo::isFile(): bool
public function SplFileInfo::isLink(): bool
public function SplFileInfo::isReadable(): bool
public function SplFileInfo::isWritable(): bool
public function SplFileInfo::openFile(string `$mode` = "r", bool `$useIncludePath` = `false`, ?resource `$context` = `null`): SplFileObject
public function SplFileInfo::setFileClass(string `$class` = `SplFileObject::class`): void
public function SplFileInfo::setInfoClass(string `$class` = `SplFileInfo::class`): void
public function SplFileInfo::__toString(): string
}

# PharData::addEmptyDir

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::addEmptyDir — 空のディレクトリを tar/zip アーカイブに追加する

### 説明

public function 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 アーカイブに追加する

# PharData::addFile

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::addFile — ファイルシステム上のファイルを tar/zip アーカイブに追加する

### 説明

public function 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 アーカイブに追加する

# PharData::addFromString

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::addFromString — 内容を文字列で指定したファイルを、tar/zip アーカイブに追加する

### 説明

public function 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 アーカイブに追加する

# PharData::buildFromDirectory

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::buildFromDirectory — ディレクトリ内のファイルから tar/zip アーカイブを作成する

### 説明

public function 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 アーカイブを作成する

# PharData::buildFromIterator

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::buildFromIterator — イテレータから tar あるいは zip アーカイブを作成する

### 説明

public function 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 アーカイブを作成する

# PharData::compress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::compress — tar/zip アーカイブ全体を Gzip あるいは Bzip2 で圧縮する

### 説明

public function 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 で圧縮する

# PharData::compressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::compressFiles — 現在の tar/zip アーカイブ内のすべてのファイルを圧縮する

### 説明

public function 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 アーカイブ全体の圧縮を解除する

# PharData::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::__construct — 実行可能でない tar あるいは zip アーカイブオブジェクトを作成する

### 説明

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

# PharData::convertToData

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::convertToData — phar アーカイブを実行可能でない tar あるいは zip ファイルに変換する

### 説明

public function 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 アーカイブ形式に変換する

# PharData::convertToExecutable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::convertToExecutable — 実行可能でない tar/zip アーカイブを実行可能な phar アーカイブ形式に変換する

### 説明

public function 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 ファイルに変換する

# PharData::copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::copy — tar/zip アーカイブ内のファイルを、同じアーカイブ内で別の新しいファイルとしてコピーする

### 説明

public function PharData::copy(string `$from`, string `$to`): true

phar アーカイブ内のファイルを、そのアーカイブ内で別の新しいファイルとしてコピーします。 これは、phar ストリームラッパーでの copy() と同等の操作をオブジェクト指向で行うものです。

### パラメータ

`from`

`to`

### 戻り値

常に `true` を返します。

### エラー / 例外

コピー元のファイルが存在しない、コピー先のファイルが既に存在する、 書き込みアクセスが無効になっている、どちらかのファイルのオープンに失敗した、 あるいはコピー元のファイルの読み込みに失敗した場合に UnexpectedValueException をスローします。 変更内容の phar への書き込みに失敗した場合は PharException をスローします。

### 例

例1 PharData::copy() の例

この例は、PharData::copy() の使用法のほかに それと同等の操作をストリームラッパーで行う方法を示すものです。 これらの方式の最大の違いはエラー処理です。 PharData のすべてのメソッドは例外をスローしますが、ストリームラッパーの場合は trigger_error() を使用します。

    <?php

    try {
        $phar = new PharData('myphar.tar');

        $phar['a'] = 'hi';
        $phar->copy('a', 'b');

        echo $phar['b']; // 出力は "phar://myphar.tar/b"
    } catch (Exception $e) {
        // エラー処理
    }

    // 上のコードと同等の処理をストリームラッパーで行う例。
    // エラー時には例外ではなく E_WARNINGS が発生します
    copy('phar://myphar.tar/a', 'phar//myphar.tar/c');
    echo file_get_contents('phar://myphar.tar/c'); // 出力は "hi"

    ?>

# PharData::decompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::decompress — Phar アーカイブ全体の圧縮を解除する

### 説明

public function 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 アーカイブ内のすべてのファイルの圧縮を解除する

# PharData::decompressFiles

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::decompressFiles — 現在の zip アーカイブ内のすべてのファイルの圧縮を解除する

### 説明

public function PharData::decompressFiles(): true

> 注意: このメソッドは、php.ini の `phar.readonly` が `0` でないと Phar オブジェクトで動作しません。それ以外の場合は PharException がスローされます。

tar 形式の phar アーカイブでは、このメソッドは BadMethodCallException をスローします。 というのも、tar ファイルフォーマットではアーカイブ内の個別のファイルの圧縮をサポートしていないからです。 PharData::compress() を使用して、tar 形式の phar アーカイブ全体を圧縮します。

zip 形式のアーカイブでは、 このメソッドはアーカイブ内のすべてのファイルの圧縮を解除します。 もし bzip2/zlib で圧縮されているファイルがある場合は、 この機能を使用するには、zlib 拡張モジュールあるいは bzip2 拡張モジュールが有効になっている必要があります。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

常に `true` を返します。

### エラー / 例外

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 アーカイブ全体の圧縮を解除する

# PharData::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::delMetadata — zip アーカイブのグローバルメタデータを削除する

### 説明

public function PharData::delMetadata(): true

> 注意: このメソッドは、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 のグローバルメタデータを削除する

# PharData::delete

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::delete — tar/zip アーカイブ内のファイルを削除する

### 説明

public function PharData::delete(string `$localName`): true

アーカイブ内のファイルを削除します。 これは、ストリームラッパー上で 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 アーカイブ内のファイルを削除する

# PharData::__destruct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::__destruct — 実行不能な tar や zip アーカイブオブジェクトを破棄する

### 説明

public function PharData::__destruct()

### パラメータ

この関数にはパラメータはありません。

# PharData::extractTo

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::extractTo — tar/zip アーカイブの内容をディレクトリに展開する

### 説明

public function 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 アーカイブの内容をディレクトリに展開する

# PharData::isWritable

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::isWritable — tar/zip アーカイブが変更可能な場合に true を返す

### 説明

public function PharData::isWritable(): bool

このメソッドは、ディスク上の tar/zip アーカイブが読み込み専用でない場合に `true` を返します。Phar::isWritable() とは異なり、 データのみの tar/zip アーカイブは `phar.readonly` が `1` であっても変更可能です。

### パラメータ

パラメータはありません。

### 戻り値

tar/zip アーカイブが変更可能な場合に `true` を返します。

### 参考

- Phar::canWrite() - phar 拡張モジュールが phar の書き込みや作成をサポートしているかどうかを返す
- Phar::isWritable() - phar アーカイブが変更可能な場合に true を返す

# PharData::offsetSet

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::offsetSet — tar/zip の内部のファイルに、外部ファイルあるいは文字列の内容を設定する

### 説明

public function 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() - 内部ファイルに、外部ファイルの内容を設定する

# PharData::offsetUnset

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::offsetUnset — ファイルを tar/zip アーカイブから削除する

### 説明

public function 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 から削除する

# PharData::setAlias

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::setAlias — ダミー関数 (Phar::setAlias は PharData では使用不能)

### 説明

public function PharData::setAlias(string `$alias`): bool

実行可能でない tar/zip アーカイブはエイリアスを持つことができないので、 このメソッドは単に例外をスローします。

### パラメータ

`alias`

  このアーカイブを指すときに使用する短い文字列。 `phar` ストリームラッパーがアクセスする際にこれを使用します。 このパラメータは無視されます。

### 戻り値

### エラー / 例外

このメソッドがコールされると必ず PharException をスローします。

### 参考

- Phar::setAlias() - Phar アーカイブのエイリアスを設定する

# PharData::setDefaultStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::setDefaultStub — ダミー関数 (Phar::setDefaultStub は PharData では無効)

### 説明

public function 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 ローダー (起動スタブ) をデフォルトのローダーに設定する

# PharData::setMetadata

(No version information available, might only be in Git)

PharData::setMetadata — phar アーカイブのメタデータを設定する

### 説明

public function 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() - ファイルがグローバルなメタデータを持つかどうかを返す

# PharData::setSignatureAlgorithm

(No version information available, might only be in Git)

PharData::setSignatureAlgorithm — phar のシグネチャのアルゴリズムを設定する

### 説明

public function 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 シグネチャを返す

# PharData::setStub

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharData::setStub — ダミー関数 (Phar::setStub は PharData では使用不能)

### 説明

public function PharData::setStub(resource|string `$stub`, int `$length` = -1): true

実行可能でない tar/zip アーカイブはスタブを持つことができないので、 このメソッドは単に例外をスローします。

### パラメータ

`stub`
  形式上は、文字列あるいはオープンしたストリームハンドル。 この phar アーカイブの実行スタブとして使用します。 このパラメータは無視されます。
`length`
  `stub` のバイト数。このパラメータは無視されます。

### 戻り値

常に `true` を返します。

### エラー / 例外

このメソッドがコールされると必ず PharException をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 戻り値の型が、`true` になりました。これより前のバージョンでは、bool でした。

### 参考

- Phar::setStub() - Phar アーカイブの PHP ローダ (あるいは起動スタブ) を設定する

## 目次

- 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 — tar/zip アーカイブ内のファイルを、同じアーカイブ内で別の新しいファイルとしてコピーする
- 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 クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

## はじめに

PharFileInfo クラスは、 phar アーカイブ内の個々のファイルのコンテンツや属性への 高レベルインターフェイスを提供します。

## クラス概要

class PharFileInfo extends SplFileInfo {
/* メソッド */
public function __construct(string `$filename`)
public function chmod(int `$perms`): void
public function compress(int `$compression`): true
public function decompress(): true
public function delMetadata(): true
public function getCRC32(): int
public function getCompressedSize(): int
public function getContent(): string
public function getMetadata(array `$unserializeOptions` = []): mixed
public function getPharFlags(): int
public function hasMetadata(): bool
public function isCRCChecked(): bool
public function isCompressed(?int `$compression` = `null`): bool
public function setMetadata(mixed `$metadata`): void
public function __destruct()
/* 継承したメソッド */
public function SplFileInfo::getATime(): int|false
public function SplFileInfo::getBasename(string `$suffix` = ""): string
public function SplFileInfo::getCTime(): int|false
public function SplFileInfo::getExtension(): string
public function SplFileInfo::getFileInfo(?string `$class` = `null`): SplFileInfo
public function SplFileInfo::getFilename(): string
public function SplFileInfo::getGroup(): int|false
public function SplFileInfo::getInode(): int|false
public function SplFileInfo::getLinkTarget(): string|false
public function SplFileInfo::getMTime(): int|false
public function SplFileInfo::getOwner(): int|false
public function SplFileInfo::getPath(): string
public function SplFileInfo::getPathInfo(?string `$class` = `null`): ?SplFileInfo
public function SplFileInfo::getPathname(): string
public function SplFileInfo::getPerms(): int|false
public function SplFileInfo::getRealPath(): string|false
public function SplFileInfo::getSize(): int|false
public function SplFileInfo::getType(): string|false
public function SplFileInfo::isDir(): bool
public function SplFileInfo::isExecutable(): bool
public function SplFileInfo::isFile(): bool
public function SplFileInfo::isLink(): bool
public function SplFileInfo::isReadable(): bool
public function SplFileInfo::isWritable(): bool
public function SplFileInfo::openFile(string `$mode` = "r", bool `$useIncludePath` = `false`, ?resource `$context` = `null`): SplFileObject
public function SplFileInfo::setFileClass(string `$class` = `SplFileObject::class`): void
public function SplFileInfo::setInfoClass(string `$class` = `SplFileInfo::class`): void
public function SplFileInfo::__toString(): string
}

# PharFileInfo::chmod

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::chmod — ファイル固有のパーミッションビットを設定する

### 説明

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

# PharFileInfo::compress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharFileInfo::compress — 現在の Phar エントリを zlib あるいは bzip2 のいずれかで圧縮する

### 説明

public function PharFileInfo::compress(int `$compression`): true

このメソッドは、Phar アーカイブ内のファイルを bzip あるいは zlib で圧縮します。 この機能を使用するには bzip2 拡張モジュールあるいは zlib 拡張モジュールが有効になっていなければなりません。 さらに、ファイルがすでに圧縮されている場合には、 その圧縮をいったん解除するために対応する拡張モジュールが必要となります。 この関数は phar の内容を変更するので、Phar アーカイブ内のファイルを扱うには INI 設定 phar.readonly が off になっていなければなりません。 PharData アーカイブ内のファイルについてはこの制約はありません。

### パラメータ

`compression`

  `Phar::GZ` または `Phar::BZ2` を指定しなければいけません。

### 戻り値

常に `true` を返します。

### エラー / 例外

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() - サポートする圧縮アルゴリズムの配列を返す

# PharFileInfo::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::__construct — Phar エントリオブジェクトを作成する

### 説明

public function 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

# PharFileInfo::decompress

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 2.0.0)

PharFileInfo::decompress — phar 内の現在の Phar エントリの圧縮を解除する

### 説明

public function PharFileInfo::decompress(): true

このメソッドは、Phar アーカイブ内のファイルの圧縮を解除します。 ファイルの圧縮形式に応じて、この機能を使用するには bzip2 拡張モジュールあるいは zlib 拡張モジュールが有効になっていなければなりません。 この関数は phar の内容を変更するので、Phar アーカイブ内のファイルを扱うには INI 設定 phar.readonly が off になっていなければなりません。 PharData アーカイブ内のファイルについてはこの制約はありません。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

常に `true` を返します。

### エラー / 例外

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::delMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

PharFileInfo::delMetadata — エントリのメタデータを削除する

### 説明

public function PharFileInfo::delMetadata(): true

エントリのメタデータが存在する場合にそれを削除します。

### パラメータ

パラメータはありません。

### 戻り値

常に `true` を返します。 この関数は 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 アーカイブのメタデータを返す

# PharFileInfo::__destruct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::__destruct — Phar エントリオブジェクトを破棄する

### 説明

public function PharFileInfo::__destruct()

### パラメータ

この関数にはパラメータはありません。

# PharFileInfo::getCRC32

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getCRC32 — CRC32 コードを返すか、CRC がチェックできない場合に例外をスローする

### 説明

public function 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

# PharFileInfo::getCompressedSize

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getCompressedSize — Phar アーカイブ内での実際のファイルの大きさ (圧縮された状態) を返す

### 説明

public function 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::getContent

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

PharFileInfo::getContent — エントリの完全なファイルの内容を取得する

### 説明

public function PharFileInfo::getContent(): string

この関数は file_get_contents() のように振る舞いますが、 Phar 専用です。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

ファイルの内容を返します。

# PharFileInfo::getMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getMetadata — ファイルとともに保存されている、ファイル固有のメタデータを返す

### 説明

public function 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 アーカイブのメタデータを返す

# PharFileInfo::getPharFlags

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::getPharFlags — Phar ファイルエントリのフラグを返す

### 説明

public function 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::hasMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.2.0)

PharFileInfo::hasMetadata — エントリのメタデータを返す

### 説明

public function PharFileInfo::hasMetadata(): bool

phar アーカイブ内のファイルのメタデータを返します。

### パラメータ

パラメータはありません。

### 戻り値

メタデータが設定されていないかあるいは `null` が設定されている場合に `false`、 `null` 以外のメタデータが設定されている場合に `true` を返します。

### 参考

- PharFileInfo::setMetadata() - ファイルとともに保存する、ファイル固有のメタデータを設定する
- PharFileInfo::getMetadata() - ファイルとともに保存されている、ファイル固有のメタデータを返す
- PharFileInfo::delMetadata() - エントリのメタデータを削除する
- Phar::setMetadata() - phar アーカイブのメタデータを設定する
- Phar::hasMetadata() - ファイルがグローバルなメタデータを持つかどうかを返す
- Phar::getMetadata() - phar アーカイブのメタデータを返す

# PharFileInfo::isCRCChecked

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::isCRCChecked — ファイルエントリの CRC が検証されているかどうかを調べる

### 説明

public function 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::isCompressed

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::isCompressed — エントリが圧縮されているかどうかを調べる

### 説明

public function 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::setMetadata

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL phar >= 1.0.0)

PharFileInfo::setMetadata — ファイルとともに保存する、ファイル固有のメタデータを設定する

### 説明

public function 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 アーカイブのメタデータを返す

## 目次

- 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 クラス

(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 function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

- インストール/設定
  - 要件
  - インストール手順
  - 実行時設定
  - リソース型
- 定義済み定数
- 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 — tar/zip アーカイブ内のファイルを、同じアーカイブ内で別の新しいファイルとしてコピーする
  - 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 クラス

# Rar アーカイブ

# はじめに

RAR は、Eugene Roshal が作成した強力で効率的なアーカイバです。 この拡張モジュールは unRAR ライブラリを使用していますが、 このライブラリは Rar アーカイブの読み込みしかサポートしていません。 unRAR のソースを使用して RAR/WinRAR アーカイバを作成することは、 unRAR のライセンス上で禁じられています。

RAR および unRAR についてのより詳細な情報は » http://www.rarlabs.com/ で見つけられます。

# インストール/設定

## 目次

- インストール手順
- リソース型

## インストール手順

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 で有効にします。

## リソース型

この拡張モジュールは三つの内部クラスを使います。 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 関数

# rar_wrapper_cache_stats

(PECL rar >= 3.0.0)

rar_wrapper_cache_stats — URL ラッパーのキャッシュのヒット数

### 説明

function rar_wrapper_cache_stats(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

## 目次

- rar_wrapper_cache_stats — URL ラッパーのキャッシュのヒット数

# RarArchive クラス

(PECL rar >= 2.0.0)

## はじめに

このクラスは RAR アーカイブをあらわします。これは複数のパーツで構成されることもあり、 中に RAR エントリ (ファイルやディレクトリ、そしてシンボリックリンクなどの特殊なオブジェクト) を含みます。

このクラスのオブジェクトの中身を走査したり、RAR アーカイブに格納されているエントリを取り出したりすることができます。 このエントリは、RarArchive::getEntry() や RarArchive::getEntries() を使って取得することもできます。

## クラス概要

final class RarArchive implements Traversable {
/* メソッド */
public function close(): bool
public function getComment(): string
public function getEntries(): array|false
public function getEntry(string `$entryname`): RarEntry|false
public function isBroken(): bool
public function isSolid(): bool
public static function open(string `$filename`, string `$password` = NULL, callable `$volume_callback` = NULL): RarArchive|false
public function setAllowBroken(bool `$allow_broken`): bool
public function __toString(): string
}

# RarArchive::close

# rar_close

(PECL rar >= 2.0.0)

RarArchive::close -- rar_close — Rar アーカイブをクローズし、全リソースを開放する

### 説明

オブジェクト指向型 (メソッド)

public function RarArchive::close(): bool

手続き型:

function 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";
    ?>

# RarArchive::getComment

# rar_comment_get

(PECL rar >= 2.0.0)

RarArchive::getComment -- rar_comment_get — RAR アーカイブのコメントテキストを取得する

### 説明

オブジェクト指向型 (メソッド)

public function RarArchive::getComment(): string

手続き型:

function 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);
    ?>

# RarArchive::getEntries

# rar_list

(PECL rar >= 2.0.0)

RarArchive::getEntries -- rar_list — RAR アーカイブからエントリの全一覧を取得する

### 説明

オブジェクト指向型 (メソッド)

public function RarArchive::getEntries(): array|false

手続き型:

function 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://` ラッパー

# RarArchive::getEntry

# rar_entry_get

(PECL rar >= 2.0.0)

RarArchive::getEntry -- rar_entry_get — Rar アーカイブからエントリオブジェクトを取得する

### 説明

オブジェクト指向型 (メソッド)

public function RarArchive::getEntry(string `$entryname`): RarEntry|false

手続き型:

function 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::isBroken

# rar_broken_is

(PECL rar >= 3.0.0)

RarArchive::isBroken -- rar_broken_is — アーカイブが壊れている (未完成である) かどうかを調べる

### 説明

オブジェクト指向型 (メソッド)

public function RarArchive::isBroken(): bool

手続き型:

function 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() - 壊れたアーカイブのオープンを許可するかどうかを設定する

# RarArchive::isSolid

# rar_solid_is

(PECL rar >= 2.0.0)

RarArchive::isSolid -- rar_solid_is — RAR アーカイブがソリッドであるかどうかを調べる

### 説明

オブジェクト指向型 (メソッド)

public function RarArchive::isSolid(): bool

手続き型:

function 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";
    ?>

# RarArchive::open

# rar_open

(PECL rar >= 2.0.0)

RarArchive::open -- rar_open — Rar アーカイブをオープンする

### 説明

オブジェクト指向型 (メソッド)

public static function RarArchive::open(string `$filename`, string `$password` = NULL, callable `$volume_callback` = NULL): RarArchive|false

手続き型:

function 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::setAllowBroken

(PECL rar >= 3.0.0)

RarArchive::setAllowBroken — 壊れたアーカイブのオープンを許可するかどうかを設定する

### 説明

オブジェクト指向型 (メソッド)

public function RarArchive::setAllowBroken(bool `$allow_broken`): bool

手続き型:

function 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::__toString

(PECL rar >= 2.0.0)

RarArchive::__toString — テキスト形式で取得する

### 説明

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

## 目次

- RarArchive::close — Rar アーカイブをクローズし、全リソースを開放する
- RarArchive::getComment — RAR アーカイブのコメントテキストを取得する
- RarArchive::getEntries — RAR アーカイブからエントリの全一覧を取得する
- RarArchive::getEntry — Rar アーカイブからエントリオブジェクトを取得する
- RarArchive::isBroken — アーカイブが壊れている (未完成である) かどうかを調べる
- RarArchive::isSolid — RAR アーカイブがソリッドであるかどうかを調べる
- RarArchive::open — Rar アーカイブをオープンする
- RarArchive::setAllowBroken — 壊れたアーカイブのオープンを許可するかどうかを設定する
- RarArchive::__toString — テキスト形式で取得する

# 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 function extract(
string `$dir`,
string `$filepath` = "",
string `$password` = NULL,
bool `$extended_data` = `false`
): bool
public function getAttr(): int
public function getCrc(): string
public function getFileTime(): string
public function getHostOs(): int
public function getMethod(): int
public function getName(): string
public function getPackedSize(): int
public function getStream(string `$password` = ?): resource|false
public function getUnpackedSize(): int
public function getVersion(): int
public function isDirectory(): bool
public function isEncrypted(): bool
public function __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

(PECL rar >= 0.1)

RarEntry::extract — アーカイブのエントリを展開する

### 説明

public function 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::getAttr

(PECL rar >= 0.1)

RarEntry::getAttr — エントリの属性を取得する

### 説明

public function 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

# RarEntry::getCrc

(PECL rar >= 0.1)

RarEntry::getCrc — エントリの CRC を取得する

### 説明

public function RarEntry::getCrc(): string

アーカイブエントリの CRC を、十六進文字列表現で返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

アーカイブエントリの CRC、あるいはエラー時に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
PECL rar 2.0.0 | 複数ボリュームのアーカイブでも正しい値を返すようになりました。

# RarEntry::getFileTime

(PECL rar >= 0.1)

RarEntry::getFileTime — エントリの最終更新時刻を取得する

### 説明

public function RarEntry::getFileTime(): string

エントリの最終更新時刻を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

エントリの最終更新時刻を `YYYY-MM-DD HH:II:SS` 形式で表した文字列、あるいはエラー時に `false` を返します。

# RarEntry::getHostOs

(PECL rar >= 0.1)

RarEntry::getHostOs — エントリのホスト OS を取得する

### 説明

public function 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::getMethod

(PECL rar >= 0.1)

RarEntry::getMethod — エントリの圧縮方法を取得する

### 説明

public function 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::getName

(PECL rar >= 0.1)

RarEntry::getName — エントリの名前を取得する

### 説明

public function 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::getPackedSize

(PECL rar >= 0.1)

RarEntry::getPackedSize — 圧縮後のエントリのサイズを取得する

### 説明

public function RarEntry::getPackedSize(): int

圧縮後のアーカイブエントリのサイズを取得します。

> 注意: 長整数型 (long) が 32 ビットであるプラットフォーム (Windows x64 など) では、返されるサイズの上限は 2 GiB となります。定数 `PHP_INT_MAX` をチェックしましょう。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

圧縮後のサイズ、あるいはエラー時に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
PECL rar 2.0.0 | このメソッドは、64 ビット int 型のプラットフォームで 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::getStream

(PECL rar >= 2.0.0)

RarEntry::getStream — このエントリのファイルハンドラを取得する

### 説明

public function 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::getUnpackedSize

(PECL rar >= 0.1)

RarEntry::getUnpackedSize — 展開後のエントリのサイズを取得する

### 説明

public function RarEntry::getUnpackedSize(): int

展開後のアーカイブエントリのサイズを取得します。

> 注意: 長整数型 (long) が 32 ビットであるプラットフォーム (Windows x64 など) では、返されるサイズの上限は 2 GiB となります。定数 `PHP_INT_MAX` をチェックしましょう。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

展開後のサイズ、あるいはエラー時に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
PECL rar 2.0.0 | このメソッドは、64 ビット int 型のプラットフォームで 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() . " バイト";

    ?>

# RarEntry::getVersion

(PECL rar >= 0.1)

RarEntry::getVersion — このエントリを展開するのに必要な RAR プログラムの最低バージョンを取得する

### 説明

public function 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::isDirectory

(PECL rar >= 2.0.0)

RarEntry::isDirectory — このエントリがディレクトリであるかどうかを調べる

### 説明

public function 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::isEncrypted

(PECL rar >= 2.0.0)

RarEntry::isEncrypted — このエントリが暗号化されているかどうかを調べる

### 説明

public function RarEntry::isEncrypted(): bool

現在のディレクトリが暗号化されているかどうかを調べます。

> 注意: 同じ RAR アーカイブ内でも、ファイルによってパスワードが異なることがあります。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

エントリが暗号化されている場合に `true`、それ以外の場合に `false` を返します。

# RarEntry::__toString

(PECL rar >= 2.0.0)

RarEntry::__toString — エントリのテキスト表現を取得する

### 説明

public function RarEntry::__toString(): string

RarEntry::__toString() は、このエントリのテキスト表現を返します。 その内容は、まずエントリがファイルであるかディレクトリであるか (シンボリックリンクやその他の特殊オブジェクトはファイルとみなされます)、 そしてエントリ名を UTF-8 であらわしたものと CRC となります。 この形式と内容は将来変更される可能性があるので、これに依存してはいけません。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

エントリのテキスト表現を返します。

## 目次

- 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 クラス

(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 function isUsingExceptions(): bool
public static function setUsingExceptions(bool `$using_exceptions`): void
/* 継承したメソッド */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# RarException::isUsingExceptions

(PECL rar >= 2.0.0)

RarException::isUsingExceptions — 例外によるエラー処理を使っているかどうかを調べる

### 説明

public static function RarException::isUsingExceptions(): bool

RAR 関数が警告を発してエラー値を返すようになっているか、 あるいは例外をスローするようになっているかを調べます (引数の型を間違えるなどのプログラム上のエラーは含めません)。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

例外を使っている場合に `true`、それ以外の場合に `false` を返します。

### 例

例1 RarException::isUsingExceptions() の例

    <?php
    // デフォルトでは例外を使いません
    var_dump(RarException::isUsingExceptions());
    ?>

上の例の出力は、 たとえば以下のようになります。

    bool(false)

### 参考

- RarException::setUsingExceptions() - 例外によるエラー処理の有効化および無効化を行う

# RarException::setUsingExceptions

(PECL rar >= 2.0.0)

RarException::setUsingExceptions — 例外によるエラー処理の有効化および無効化を行う

### 説明

public static function 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() - 例外によるエラー処理を使っているかどうかを調べる

## 目次

- RarException::isUsingExceptions — 例外によるエラー処理を使っているかどうかを調べる
- RarException::setUsingExceptions — 例外によるエラー処理の有効化および無効化を行う

- インストール/設定
  - インストール手順
  - リソース型
- 定義済み定数
- 例
- 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 — 例外によるエラー処理の有効化および無効化を行う

# Zip

# はじめに

この拡張モジュールにより、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::ER_TRUNCATED_ZIP` (int)
  zip アーカイブが切り詰められているか破損している可能性があります。 PHP 8.4.0 以降、 PECL zip 1.22.4 以降で利用可能です。 それぞれ、libzip ≥ 1.11.1 以降でビルドした場合に利用できます。

暗号化モード
`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 ER_TRUNCATED_ZIP;
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 function addEmptyDir(string `$dirname`, int `$flags` = 0): bool
public function addFile(
string `$filepath`,
string `$entryname` = "",
int `$start` = 0,
int `$length` = `ZipArchive::LENGTH_TO_END`,
int `$flags` = `ZipArchive::FL_OVERWRITE`
): bool
public function addFromString(string `$name`, string `$content`, int `$flags` = `ZipArchive::FL_OVERWRITE`): bool
public function addGlob(string `$pattern`, int `$flags` = 0, array `$options` = []): array|false
public function addPattern(string `$pattern`, string `$path` = ".", array `$options` = []): array|false
public function clearError(): void
public function close(): bool
public function count(): int
public function deleteIndex(int `$index`): bool
public function deleteName(string `$name`): bool
public function extractTo(string `$pathto`, array|string|null `$files` = `null`): bool
public function getArchiveComment(int `$flags` = 0): string|false
public function getArchiveFlag(int `$flag`, int `$flags` = 0): int
public function getCommentIndex(int `$index`, int `$flags` = 0): string|false
public function getCommentName(string `$name`, int `$flags` = 0): string|false
public function getExternalAttributesIndex(
int `$index`,
int `&$opsys`,
int `&$attr`,
int `$flags` = 0
): bool
public function getExternalAttributesName(
string `$name`,
int `&$opsys`,
int `&$attr`,
int `$flags` = 0
): bool
public function getFromIndex(int `$index`, int `$len` = 0, int `$flags` = 0): string|false
public function getFromName(string `$name`, int `$len` = 0, int `$flags` = 0): string|false
public function getNameIndex(int `$index`, int `$flags` = 0): string|false
public function getStatusString(): string
public function getStream(string `$name`): resource|false
public function getStreamIndex(int `$index`, int `$flags` = 0): resource|false
public function getStreamName(string `$name`, int `$flags` = 0): resource|false
public static function isCompressionMethodSupported(int `$method`, bool `$enc` = `true`): bool
public static function isEncryptionMethodSupported(int `$method`, bool `$enc` = `true`): bool
public function locateName(string `$name`, int `$flags` = 0): int|false
public function open(string `$filename`, int `$flags` = 0): bool|int
public function registerCancelCallback(callable `$callback`): bool
public function registerProgressCallback(float `$rate`, callable `$callback`): bool
public function renameIndex(int `$index`, string `$new_name`): bool
public function renameName(string `$name`, string `$new_name`): bool
public function replaceFile(
string `$filepath`,
int `$index`,
int `$start` = 0,
int `$length` = `ZipArchive::LENGTH_TO_END`,
int `$flags` = 0
): bool
public function setArchiveComment(string `$comment`): bool
public function setArchiveFlag(int `$flag`, int `$value`): bool
public function setCommentIndex(int `$index`, string `$comment`): bool
public function setCommentName(string `$name`, string `$comment`): bool
public function setCompressionIndex(int `$index`, int `$method`, int `$compflags` = 0): bool
public function setCompressionName(string `$name`, int `$method`, int `$compflags` = 0): bool
public function setEncryptionIndex(int `$index`, int `$method`, #[\SensitiveParameter] ?string `$password` = `null`): bool
public function setEncryptionName(string `$name`, int `$method`, #[\SensitiveParameter] ?string `$password` = `null`): bool
public function setExternalAttributesIndex(
int `$index`,
int `$opsys`,
int `$attr`,
int `$flags` = 0
): bool
public function setExternalAttributesName(
string `$name`,
int `$opsys`,
int `$attr`,
int `$flags` = 0
): bool
public function setMtimeIndex(int `$index`, int `$timestamp`, int `$flags` = 0): bool
public function setMtimeName(string `$name`, int `$timestamp`, int `$flags` = 0): bool
public function setPassword(#[\SensitiveParameter] string `$password`): bool
public function statIndex(int `$index`, int `$flags` = 0): array|false
public function statName(string `$name`, int `$flags` = 0): array|false
public function unchangeAll(): bool
public function unchangeArchive(): bool
public function unchangeIndex(int `$index`): bool
public function 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

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.8.0)

ZipArchive::addEmptyDir — 新しいディレクトリを追加する

### 説明

public function 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, PECL zip 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 '失敗しました';
    }
    ?>

# ZipArchive::addFile

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::addFile — 指定したパスからファイルを ZIP アーカイブに追加する

### 説明

public function 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, PECL zip 1.18.0 | `flags` が追加されました。
8.3.0, PECL zip 1.22.1 | `ZipArchive::FL_OPEN_FILE_NOW` が追加されました。
8.3.0, PECL zip 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() - 指定されたパスのファイルにアーカイブの一部を置き換える

# ZipArchive::addFromString

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::addFromString — 内容を指定して、ファイルを ZIP アーカイブに追加する

### 説明

public function 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, PECL zip 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 '失敗';
    }
    ?>

# ZipArchive::addGlob

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL zip >= 1.9.0)

ZipArchive::addGlob — ディレクトリから、glob パターンを使ってファイルを追加する

### 説明

public function 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, PECL zip 1.18.0 | `options` に `"flags"` が追加されました。
8.0.0, PECL zip 1.18.1 | `options` に `"comp_method"`, `"comp_flags"`, `"enc_method"`, `"enc_password"` が追加されました。
8.3.0, PECL zip 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 パターンを使ってファイルを追加する

# ZipArchive::addPattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL zip >= 1.9.0)

ZipArchive::addPattern — ディレクトリから、PCRE パターンを使ってファイルを追加する

### 説明

public function 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 パターンを使ってファイルを追加する

# ZipArchive::clearError

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::clearError — ステータスエラーメッセージか、システムエラー/ zip メッセージをクリアする

### 説明

public function ZipArchive::clearError(): void

アーカイブのステータスエラーメッセージか、 システムエラー かつ/または zip メッセージをクリアします。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

値を返しません。

### 参考

- ZipArchive::getStatusString() - システムエラー、または ZIP メッセージに関するエラー情報を返す

# ZipArchive::close

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::close — アクティブな (オープンされた、あるいは新しく作成された) アーカイブを閉じる

### 説明

public function ZipArchive::close(): bool

オープンされた、あるいは作成されたアーカイブを閉じ、 変更内容を保存します。このメソッドは、 スクリプトの最後で自動的にコールされます。

アーカイブにファイルが含まれていない場合、 グローバルフラグ `ZipArchive::AFL_CREATE_OR_KEEP_FILE_FOR_EMPTY_ARCHIVE` に従って、 デフォルトではファイルは完全に削除されます。 (空のアーカイブが作られることはありません)

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- ZipArchive::setArchiveFlag() - Zip アーカイブのグローバルフラグを設定する

# ZipArchive::count

(PHP 7 >= 7.2.0, PHP 8, PECL zip >= 1.15.0)

ZipArchive::count — アーカイブにあるファイルの数を数える

### 説明

public function ZipArchive::count(): int

### パラメータ

この関数にはパラメータはありません。

### 戻り値

アーカイブにあるファイルの数を返します。

# ZipArchive::deleteIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::deleteIndex — インデックスを使用して、アーカイブ内のエントリを削除する

### 説明

public function 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::deleteName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::deleteName — 名前を使用して、アーカイブからエントリを削除する

### 説明

public function 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::extractTo

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::extractTo — アーカイブの内容を展開する

### 説明

public function 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 ファイルシステムには、ファイル名で使う場合にサポートしていない文字があります。具体的には、`<|>*?":` です。末尾にドットがあるファイル名もサポートしていません。いくつかの展開ツールと異なり、このメソッドはこれらの文字をアンダースコアで置き換えませんし、そのようなファイルを展開すると失敗します。

# ZipArchive::getArchiveComment

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getArchiveComment — ZIP アーカイブのコメントを返す

### 説明

public function 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;
    }
    ?>

# ZipArchive::getArchiveFlag

(PHP >= 8.3.0, PECL zip >= 1.22.0)

ZipArchive::getArchiveFlag — Zip アーカイブのグローバルフラグの値を返す

### 説明

public function 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`
  `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::getCommentIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::getCommentIndex — エントリのインデックスを使用して、エントリのコメントを返す

### 説明

public function 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::getCommentName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::getCommentName — エントリ名を使用して、エントリのコメントを返す

### 説明

public function 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::getExternalAttributesIndex

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::getExternalAttributesIndex — インデックスで定義されたエントリの外部属性を取得する

### 説明

public function 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::getExternalAttributesName

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::getExternalAttributesName — 名前で定義されたエントリの外部属性を取得する

### 説明

public function ZipArchive::getExternalAttributesName(
string `$name`,
int `&$opsys`,
int `&$attr`,
int `$flags` = 0
): bool

名前で定義されたエントリの外部属性を取得します。

### パラメータ

`name`
  エントリの名前
`opsys`
  成功した場合に、 ZipArchive::OPSYS_ 定数のうちのひとつで定義された、 オペレーティングシステムコードを取得します。
`attr`
  成功した場合に、外部属性を取得します。 値はオペレーティングシステム依存です。
`flags`
  `ZipArchive::FL_UNCHANGED` に設定された場合、 オリジナルの変更されなかった属性が返されます。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

# ZipArchive::getFromIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getFromIndex — インデックスを使用して、エントリの内容を返す

### 説明

public function 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::getFromName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getFromName — 名前を使用して、エントリの内容を返す

### 説明

public function 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::getNameIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::getNameIndex — インデックスを使用して、エントリの名前を返す

### 説明

public function 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);
         // ...
     }
    }
    ?>

# ZipArchive::getStatusString

(PHP 5 >= 5.2.7, PHP 7, PHP 8)

ZipArchive::getStatusString — システムエラー、または ZIP メッセージに関するエラー情報を返す

### 説明

public function ZipArchive::getStatusString(): string

システムエラー、または ZIP メッセージに関するエラー情報を返す

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功時にはステータスメッセージを文字列で返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0, PECL zip 1.18.0 | このメソッドは、閉じられたアーカイブに対しても呼び出せるようになりました。
8.0.0, PECL zip 1.18.0 | このメソッドは、失敗時に `false` を返さなくなりました。

# ZipArchive::getStream

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::getStream — 名前を使用して、エントリのファイルハンドラ (読み込み専用) を取得する

### 説明

public function 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::getStreamIndex

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::getStreamIndex — インデックスで指定されたエントリへの、ファイルハンドラを取得する(読み取り専用)

### 説明

public function 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::getStreamName

(PHP 8 >= 8.2.0, PECL zip >= 1.20.0)

ZipArchive::getStreamName — 名前で指定されたエントリへの、ファイルハンドラを取得する(読み取り専用)

### 説明

public function 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() - インデックスで指定されたエントリへの、ファイルハンドラを取得する(読み取り専用)

# ZipArchive::isCompressionMethodSupported

(PHP >= 8.0.0, PECL zip >= 1.19.0)

ZipArchive::isCompressionMethodSupported — 圧縮方式を libzip がサポートしているかをチェックする

### 説明

public static function 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() - 名前で定義されたエントリの圧縮メソッドを設定する

# ZipArchive::isEncryptionMethodSupported

(PHP >= 8.0.0, PECL zip >= 1.19.0)

ZipArchive::isEncryptionMethodSupported — 暗号化方式を libzip がサポートしているかどうかをチェックする

### 説明

public static function 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::locateName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::locateName — アーカイブ内のエントリのインデックスを返す

### 説明

public function 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

# ZipArchive::open

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::open — ZIP ファイルアーカイブをオープンする

### 説明

public function 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::registerCancelCallback

(PHP >= 8.0.0, PECL zip >= 1.17.0)

ZipArchive::registerCancelCallback — アーカイブを閉じている間にキャンセルできるようにコールバックを登録する

### 説明

public function 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::registerProgressCallback

(PHP >= 8.0.0, PECL zip >= 1.17.0)

ZipArchive::registerProgressCallback — アーカイブを閉じている間に更新できるようにコールバックを登録する

### 説明

public function 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::renameIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::renameIndex — インデックスを使用してエントリ名を変更する

### 説明

public function 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::renameName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::renameName — 名前を使用してエントリ名を変更する

### 説明

public function 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::replaceFile

(PHP >= 8.0.0, PECL zip >= 1.18.0)

ZipArchive::replaceFile — 指定されたパスのファイルにアーカイブの一部を置き換える

### 説明

public function 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, PECL zip 1.22.1 | `ZipArchive::FL_OPEN_FILE_NOW` が追加されました。
8.3.0, PECL zip 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 アーカイブに追加する

# ZipArchive::setArchiveComment

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setArchiveComment — ZIP アーカイブのコメントを設定する

### 説明

public function 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';
    }
    ?>

# ZipArchive::setArchiveFlag

(PHP >= 8.3.0, PECL zip >= 1.22.0)

ZipArchive::setArchiveFlag — Zip アーカイブのグローバルフラグを設定する

### 説明

public function 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::setCommentIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setCommentIndex — インデックスを使用してエントリのコメントを設定する

### 説明

public function 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::setCommentName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.4.0)

ZipArchive::setCommentName — 名前を使用してエントリのコメントを設定する

### 説明

public function 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::setCompressionIndex

(PHP 7, PHP 8, PECL zip >= 1.13.0)

ZipArchive::setCompressionIndex — インデックスで定義されたエントリの圧縮方法を設定する

### 説明

public function 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::setCompressionName

(PHP 7, PHP 8, PECL zip >= 1.13.0)

ZipArchive::setCompressionName — 名前で定義されたエントリの圧縮メソッドを設定する

### 説明

public function 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';
    }
    ?>

# ZipArchive::setEncryptionIndex

(PHP >= 7.2.0, PHP 8, PECL zip >= 1.14.0)

ZipArchive::setEncryptionIndex — index で定義されたエントリの暗号化方法を指定する

### 説明

public function 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::setEncryptionName

(PHP >= 7.2.0, PHP 8, PECL zip >= 1.14.0)

ZipArchive::setEncryptionName — 名前で定義されたエントリの暗号化方式を設定する

### 説明

public function 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::setExternalAttributesIndex

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setExternalAttributesIndex — インデックスで定義されたエントリの外部属性を設定する

### 説明

public function ZipArchive::setExternalAttributesIndex(
int `$index`,
int `$opsys`,
int `$attr`,
int `$flags` = 0
): bool

インデックスで定義されたエントリの外部属性を設定します。

### パラメータ

`index`
  エントリのインデックス
`opsys`
  ZipArchive::OPSYS_ 定数のうちのひとつで定義された、 オペレーティングシステムコード
`attr`
  外部属性。 値はオペレーティングシステム依存です。
`flags`
  オプションのフラグ。現在は使われていません。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

# ZipArchive::setExternalAttributesName

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setExternalAttributesName — 名前で定義されたエントリの外部属性を設定する

### 説明

public function 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::setMtimeIndex

(PHP >= 8.0.0, PECL zip >= 1.16.0)

ZipArchive::setMtimeIndex — インデックスを使用してエントリの変更時間を設定する

### 説明

public function 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::setMtimeName

(PHP >= 8.0.0, PECL zip >= 1.16.0)

ZipArchive::setMtimeName — 名前を使ってエントリの変更時間を設定する

### 説明

public function 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::setPassword

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL zip >= 1.12.4)

ZipArchive::setPassword — アクティブなアーカイブにパスワードを設定する

### 説明

public function 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::statIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::statIndex — インデックスを使用してエントリの詳細を取得する

### 説明

public function 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::statName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::statName — 名前を使用してエントリの詳細を取得する

### 説明

public function 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::unchangeAll

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeAll — アーカイブに対するすべての変更を取り消す

### 説明

public function ZipArchive::unchangeAll(): bool

アーカイブに対するすべての変更を取り消します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

# ZipArchive::unchangeArchive

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeArchive — アーカイブ全体に対して行われたすべての変更を取り消す

### 説明

public function ZipArchive::unchangeArchive(): bool

アーカイブ全体に対して行われたすべての変更を取り消します。 現在は、これはアーカイブのコメントに対する変更のみを取り消します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

# ZipArchive::unchangeIndex

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.1.0)

ZipArchive::unchangeIndex — 指定したインデックスのエントリに対するすべての変更を取り消す

### 説明

public function ZipArchive::unchangeIndex(int `$index`): bool

指定したインデックスのエントリに対するすべての変更を取り消します。

### パラメータ

`index`
  エントリのインデックス。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

# ZipArchive::unchangeName

(PHP 5 >= 5.2.0, PHP 7, PHP 8, PECL zip >= 1.5.0)

ZipArchive::unchangeName — 指定した名前のエントリに対するすべての変更を取り消す

### 説明

public function ZipArchive::unchangeName(string `$name`): bool

エントリに対するすべての変更を取り消します。

### パラメータ

`name`
  エントリの名前。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

## 目次

- 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 関数

警告

手続き型のAPI は PHP 8.0.0 以降、推奨されなくなりました。 代わりに ZipArchive クラスを使うべきです。

# 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 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function zip_close(resource `$zip`): void

ZIP ファイルアーカイブを閉じます。

### パラメータ

`zip`
  事前に zip_open() でオープンされた ZIP ファイル。

### 戻り値

値を返しません。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | この関数は非推奨になりました。オブジェクト指向のAPIを使うのが望ましいです。 ZipArchive::close() を参照ください。

### 参考

- zip_open() - Zip ファイルアーカイブをオープンする
- zip_read() - 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 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function 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_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 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function 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_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 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function 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_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 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function 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_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 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function 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_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 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function 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_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 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function 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_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 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function 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_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 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function 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() - オープンされたディレクトリエントリから読み込む

## 目次

- 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 ファイルアーカイブの中の次のエントリを読み込む

- インストール/設定
  - 要件
  - インストール手順
  - リソース型
- 定義済み定数
- 例
- 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 ファイルアーカイブの中の次のエントリを読み込む

# Zlib 圧縮

# はじめに

このモジュールにより gzip (.gz) で圧縮されたファイルを読み書きすることが可能となります。 この際、ファイルシステム 関数の gzip 圧縮対応版 (非圧縮ファイルも扱えますが、 ソケットは扱えません)を使用します。

> 注意:

> PHP には、.gz ファイルに対応した fopen のラッパーが搭載されています。 詳細な情報は、 zlib:// にあります。

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定
- リソース型

## 要件

このモジュールは、Jean-loup Gailly および Mark Adler による » zlib の関数を使用します。 PHP 8.4.0 以降のバージョンで、このモジュールを使用するために必要な zlib の最低バージョンは 1.2.11 です。 PHP 8.4.0 より前のバージョンで、このモジュールを使用するために必要な 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

(PHP 7, PHP 8)

deflate_add — インクリメンタルにデータを圧縮する

### 説明

function 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_init

(PHP 7, PHP 8)

deflate_init — インクリメンタルな圧縮コンテキストを初期化する

### 説明

function deflate_init(int `$encoding`, array|object `$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() - インクリメンタルな解凍コンテキストを初期化する

# gzclose

(PHP 4, PHP 5, PHP 7, PHP 8)

gzclose — 開かれたgzファイルへのポインタを閉じる

### 説明

function 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 ファイルを開く

# gzcompress

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

gzcompress — 文字列を圧縮する

### 説明

function 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 圧縮された文字列を作成する

# gzdecode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

gzdecode — gzip 圧縮された文字列をデコードする

### 説明

function gzdecode(string `$data`, int `$max_length` = 0): string|false

この関数は、入力された `data` をデコードしたものを返します。

### パラメータ

`data`

  デコードするデータ。これは gzencode() でエンコードされたものです。

`max_length`

  デコードするデータの最大長。

### 戻り値

デコードされた文字列を返します。 失敗した場合に `false` を返します

### エラー / 例外

失敗した場合、 `E_WARNING` レベルの警告が発生します。

### 参考

- gzencode() - gzip 圧縮された文字列を作成する

# gzdeflate

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzdeflate — 文字列を deflate 圧縮する

### 説明

function 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 圧縮された文字列を作成する

# gzencode

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzencode — gzip 圧縮された文字列を作成する

### 説明

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

# gzeof

(PHP 4, PHP 5, PHP 7, PHP 8)

gzeof — gz ファイルポインタが EOF かどうか調べる

### 説明

function 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);
    ?>

# gzfile

(PHP 4, PHP 5, PHP 7, PHP 8)

gzfile — gzファイル全体を配列に読み込む

### 説明

function gzfile(string `$filename`, bool `$use_include_path` = `false`): array|false

ファイルを配列にして返すこと以外は readgzfile() と同じです。

### パラメータ

`filename`

  ファイル名を指定します。

`use_include_path`
  `true` を設定すると、include_path にあるファイルも検索します。

### 戻り値

ファイルを含む配列で、要素毎に 1 行ずつ含んでいます。空行も含み、改行もついた状態です。 失敗した場合に `false` を返します.

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | `use_include_path` の型が bool になりました。 これより前は、int でした。

### 例

例1 gzfile() の例

    <?php
    $lines = gzfile('somefile.gz');
    foreach ($lines as $line) {
        echo $line;
    }
    ?>

### 参考

- readgzfile() - gz ファイルを出力する
- gzopen() - gz ファイルを開く

# gzgetc

(PHP 4, PHP 5, PHP 7, PHP 8)

gzgetc — gz ファイルへのポインタから文字を得る

### 説明

function 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 行を得る

# gzgets

(PHP 4, PHP 5, PHP 7, PHP 8)

gzgets — ファイルポインタから 1 行を得る

### 説明

function 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 ファイル書き込み

# gzgetss

(PHP 4, PHP 5, PHP 7)

gzgetss — gzファイルへのポインタから1行を得て、HTMLタグを取り除く

警告

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

### 説明

function 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 タグを取り除く

# gzinflate

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gzinflate — deflate圧縮された文字列を解凍する

### 説明

function 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 圧縮された文字列を作成する

# gzopen

(PHP 4, PHP 5, PHP 7, PHP 8)

gzopen — gz ファイルを開く

### 説明

function gzopen(string `$filename`, string `$mode`, bool `$use_include_path` = `false`): resource|false

読み込みもしくは書き込みのために gzip (.gz) ファイルをオープンします。

gzopen() は、gzip フォーマットでないファイルの読み込みについても使用することができます。 この場合、gzread()は、ファイルを解凍せずに直接読み 込まれます。

### パラメータ

`filename`

  ファイル名を指定します

`mode`

  fopen() と同じ (`rb` または `wb`) ですが、 圧縮レベル (`wb9`) または圧縮の方策、 つまり、`wb6f` のようにフィルターを通したデータを `f` で指定したり、`h` でハフマン圧縮のみを行うことを指定したりすることができます (方策に関するパラメータの詳細については、zlib.h の中の `deflateInit2` の説明を参照ください)。

`use_include_path`
  `true` を設定すると、include_path にあるファイルも検索します。

### 戻り値

オープンしたファイルへのファイルポインタを返します。その後、 このファイルディスクプリタから読み込んだ全ては透過的に解凍され、 書き込んだものは圧縮されます。

オープンに失敗した場合、この関数は `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | `use_include_path` の型が bool になりました。 これより前は、int でした。

### 例

例1 gzopen() の例

    <?php
    $fp = gzopen("/tmp/file.gz", "r");
    ?>

### 参考

- gzclose() - 開かれたgzファイルへのポインタを閉じる

# gzpassthru

(PHP 4, PHP 5, PHP 7, PHP 8)

gzpassthru — gzファイルへのポインタから残りのデータ全部を出力する

### 説明

function 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);
    ?>

# gzputs

(PHP 4, PHP 5, PHP 7, PHP 8)

gzputs — gzwrite() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 gzwrite().

# gzread

(PHP 4, PHP 5, PHP 7, PHP 8)

gzread — バイナリ対応のgzファイル読み込み

### 説明

function 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ファイルへのポインタから残りのデータ全部を出力する

# gzrewind

(PHP 4, PHP 5, PHP 7, PHP 8)

gzrewind — gz ファイルポインタの示す位置を元に戻す

### 説明

function gzrewind(resource `$stream`): bool

与えられた gz ファイルポインタが指すファイルのファイル位置記述子を、 ファイルストリームの先頭にセットします。

### パラメータ

`stream`

  gz ファイルポインタを指定します。これは有効なファイルポインタであり、 かつ、gzopen() によりオープンできたファイルを指している必要があります。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- gzseek() - gz ファイルポインタの位置を移動する
- gztell() - gz ファイルポインタの読み込み/書き込み位置を返します

# gzseek

(PHP 4, PHP 5, PHP 7, PHP 8)

gzseek — gz ファイルポインタの位置を移動する

### 説明

function 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 ファイルポインタの示す位置を元に戻す

# gztell

(PHP 4, PHP 5, PHP 7, PHP 8)

gztell — gz ファイルポインタの読み込み/書き込み位置を返します

### 説明

function gztell(resource `$stream`): int|false

与えられたファイルポインタが指す位置、つまり、 圧縮されていないファイルストリームにおけるオフセット値を返します。

### パラメータ

`stream`

  gz ファイルポインタを指定します。これは有効なファイルポインタであり、 かつ、gzopen() によりオープンできたファイルを指している必要があります。

### 戻り値

ファイルポインタの位置、もしくはエラーが発生した場合 `false`

### 参考

- gzopen() - gz ファイルを開く
- gzseek() - gz ファイルポインタの位置を移動する
- gzrewind() - gz ファイルポインタの示す位置を元に戻す

# gzuncompress

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

gzuncompress — 圧縮された文字列を解凍する

### 説明

function 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 圧縮された文字列を作成する

# gzwrite

(PHP 4, PHP 5, PHP 7, PHP 8)

gzwrite — バイナリセーフな gz ファイル書き込み

### 説明

function 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 ファイルを開く

# inflate_add

(PHP 7, PHP 8)

inflate_add — インクリメンタルにエンコードされたデータを解凍する

### 説明

function 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_get_read_len

(PHP 7 >= 7.2.0, PHP 8)

inflate_get_read_len — これまでに読み取ったバイト数を得る

### 説明

function inflate_get_read_len(InflateContext `$context`): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`context`

### 戻り値

これまでに読み取ったバイト数を返します。 失敗した場合に `false` を返します

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `context` は、 InflateContext クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

# inflate_get_status

(PHP 7 >= 7.2.0, PHP 8)

inflate_get_status — 解凍の状態を取得する

### 説明

function inflate_get_status(InflateContext `$context`): int

通常 `ZLIB_OK` か `ZLIB_STREAM_END` を返します。

### パラメータ

`context`

### 戻り値

解凍の状態を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `context` は、 InflateContext クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

# inflate_init

(PHP 7, PHP 8)

inflate_init — インクリメンタルな解凍コンテキストを初期化する

### 説明

function inflate_init(int `$encoding`, array|object `$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() - インクリメンタルな圧縮コンテキストを初期化する

# ob_gzhandler

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

ob_gzhandler — 出力バッファを gzip 圧縮するための ob_start コールバック関数

### 説明

function 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() - アクティブな出力用バッファをフラッシュ(送信)し、アクティブな出力バッファをオフにする

# readgzfile

(PHP 4, PHP 5, PHP 7, PHP 8)

readgzfile — gz ファイルを出力する

### 説明

function readgzfile(string `$filename`, bool `$use_include_path` = `false`): int|false

ファイルを読み込み、解凍し、標準出力に書き込みます。

readgzfile()は、gzip フォーマットでないファイルの読込にも使用可能です。この場合、 readgzfile() はファイルを解凍せずに直接読込みます。

### パラメータ

`filename`

  ファイル名を指定します。このファイルはファイルシステムからオープンされ、 内容は標準出力に書き込まれます。

`use_include_path`
  `true` に設定すると、 どのファイルをオープンするかを決めるために include_path を使います。

### 戻り値

成功時は、ファイルから読み込んだ (解凍された) データのバイト数を返します。 失敗した場合に `false` を返します

### エラー / 例外

失敗したときは `E_WARNING` が発生します。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | `use_include_path` の型が bool になりました。 これより前は、int でした。

### 参考

- gzpassthru() - gzファイルへのポインタから残りのデータ全部を出力する
- gzfile() - gzファイル全体を配列に読み込む
- gzopen() - gz ファイルを開く

# zlib_decode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

zlib_decode — raw/gzip/zlib で符号化されたデータを復元する

### 説明

function zlib_decode(string `$data`, int `$max_length` = 0): string|false

raw/gzip/zlib で符号化されたデータを復元します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`data`

`max_length`

### 戻り値

圧縮されていないデータを返します。失敗した場合に `false` を返します。

### 参考

- zlib_encode() - 指定した符号化方式でデータを圧縮する

# zlib_encode

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

zlib_encode — 指定した符号化方式でデータを圧縮する

### 説明

function 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_get_coding_type

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

zlib_get_coding_type — 出力圧縮に使用されたコーディングの種類を返す

### 説明

function zlib_get_coding_type(): string|false

出力圧縮に使用されたコーディングの種類を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

返される値は `gzip`, `deflate`, もしくは `false` です。

### 参考

- zlib.output_compression ディレクティブ

## 目次

- 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 クラス

(PHP 8)

## はじめに

PHP 8.0.0 以降、 `zlib.deflate` リソースを置き換える完全不透明クラスです。

## クラス概要

final class DeflateContext {
}

# InflateContext クラス

(PHP 8)

## はじめに

PHP 8.0.0 以降、 `zlib.inflate` リソースを置き換える完全不透明クラスです。

## クラス概要

final class InflateContext {
}

- インストール/設定
  - 要件
  - インストール手順
  - 実行時設定
  - リソース型
- 定義済み定数
- 例
- 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 クラス

- 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 クラス

# 暗号

# HASH メッセージダイジェストフレームワーク

# はじめに

この拡張モジュールは、様々なハッシュアルゴリズムを使って任意の長さのメッセージを直接、または徐々に処理する関数を提供します。可能な処理には、たとえば HMAC 値の生成や、HKDF や PBKDF2 を含む、鍵の導出処理があります。

ハッシュアルゴリズムには、大きく分けて3つのカテゴリがあります。完全な一覧は hash_algos() を参照ください。

- チェックサムアルゴリズム(例: `"crc32b"`, `"adler32"`): 通信エラーを検出するときなどに役立つチェックサムを計算するのに使えます。これらは大抵、とても高速です。また、衝突したり、容易に"推測可能な" 値を生成できたりするので、暗号には完全に不向きです。
- 非暗号化アルゴリズム(例:xxHash ファミリ): ハッシュテーブルで使うハッシュ値を計算するのに用いられます。よって、任意の文字列の入力に対して、うまく分散したハッシュ値を生成するように設計されています。これらも一般的に高速ですが、暗号化の処理には向いていません。
- 暗号化アルゴリズム(例:SHA-2 ファミリ): 入力そのものを表現するものの、それが推測できず、かつ衝突もしにくいハッシュ値を生成するように設計されています。パフォーマンスは二の次とされていますが、モダンなハードウェアはこれらのアルゴリズムの処理を特別に支援するものがあり、PHP も利用可能なときはそれらを使おうとします。 NIST の Computer Security Resource Center には、 » アメリカの連邦通信処理規格(FIPS) が現在認定しているアルゴリズムの説明 があります。
  警告

  `"md4"` `"md5"`, `"sha1"` のような 初期の暗号化アルゴリズムの中には、既に衝突しやすいことが証明されているものがあります。こうしたアルゴリズムを使うことは、暗号を用いるアプリケーションでは既に推奨されません。

パスワードを処理する際にハッシュ関数を使うためのベストプラクティスに関する情報は、パスワードのハッシュに関するFAQ も参照ください。

# インストール/設定

## 目次

- インストール手順
- リソース型

## インストール手順

ハッシュ拡張モジュールはコア PHP 拡張モジュールであり、 常に有効になります。

PHP 7.4.0 より前のバージョンでは、 ハッシュ拡張モジュールは本体にバンドルされ、デフォルトでコンパイルされるようになりました。 しかし、 configure 時に --disable-hash を指定することで明示的に無効にすることも可能でした。

PHP 5.1.2 より前のバージョンでは、 ハッシュ拡張モジュールは » PECL module としてインストールされていました。

## リソース型

この拡張モジュールでは、ハッシュコンテキストリソースを定義しています。これは hash_init() が返すものです。

# 定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

`HASH_HMAC` (int)
  hash_init() のオプションのフラグです。 現在のハッシュコンテキストに対して HMAC digest-keying アルゴリズムが適用されることを示します。

# HashContext クラス

(PHP 7 >= 7.2.0, PHP 8)

## はじめに

## クラス概要

final class HashContext {
/* メソッド */
private function __construct()
public function __debugInfo(): array
public function __serialize(): array
public function __unserialize(array `$data`): void
}

# HashContext::__construct

(PHP 7 >= 7.2.0, PHP 8)

HashContext::__construct — private なコンストラクタのため、直接インスタンス化できません

### 説明

private function HashContext::__construct()

### パラメータ

この関数にはパラメータはありません。

# HashContext::__debugInfo

(PHP 8 >= 8.4.0)

HashContext::__debugInfo — ハッシュコンテキストに関するデバッグ情報を返す

### 説明

public function HashContext::__debugInfo(): array

このメソッドは、直接コールするためのものではありません。 HashContext のインスタンスを調べる際に、 var_dump() や関連する関数からコールされます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

デバッグ情報の連想配列を返します。 この配列には `algo` キーが含まれており、 そのコンテキストが使用しているハッシュアルゴリズムの名前を保持しています。

### 例

例1 HashContext::__debugInfo() の例

    <?php
    $ctx = hash_init('sha256');
    var_dump($ctx);
    ?>

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

    object(HashContext)#1 (1) {
      ["algo"]=>
      string(6) "sha256"
    }

### 参考

- hash_init() - 段階的なハッシュコンテキストを初期化する
- var_dump() - 変数に関する情報をダンプする

# HashContext::__serialize

(PHP 8)

HashContext::__serialize — HashContext オブジェクトをシリアライズする

### 説明

public function HashContext::__serialize(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

値を返しません。

# HashContext::__unserialize

(PHP 8)

HashContext::__unserialize — `data` を HashContext オブジェクト に復元する

### 説明

public function HashContext::__unserialize(array `$data`): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`data`

  アンシリアライズする値。

### 戻り値

値を返しません。

## 目次

- HashContext::__construct — private なコンストラクタのため、直接インスタンス化できません
- HashContext::__debugInfo — ハッシュコンテキストに関するデバッグ情報を返す
- HashContext::__serialize — HashContext オブジェクトをシリアライズする
- HashContext::__unserialize — data を HashContext オブジェクト に復元する

# Hash 関数

# hash

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash — ハッシュ値 (メッセージダイジェスト) を生成する

### 説明

function 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 に設定されていた場合は、メッセージダイジェストが そのままのバイナリ形式で返されます。

### エラー / 例外

`algo` が不明な場合、 ValueError がスローされます。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | `options` パラメータが追加されました。
8.0.0 | `algo` が未知の場合に、 ValueError をスローするようになりました。 これより前のバージョンでは、`false` を返し、 `E_WARNING` メッセージを発行していました。

### 例

例1 hash() の例

    <?php
    echo hash('sha256', 'The quick brown fox jumped over the lazy dog.');
    ?>

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

    68b1282b91de2c054c36629cb8dd447f12f096d3e3c587978dc2248444633483

### 参考

- hash_init() - 段階的なハッシュコンテキストを初期化する
- hash_file() - ファイルの内容から、ハッシュ値を生成する
- hash_hmac() - HMAC 方式を使用してハッシュ値を生成する

# hash_algos

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_algos — 登録されているハッシュアルゴリズムの一覧を返す

### 説明

function 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_copy

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

hash_copy — ハッシュコンテキストをコピーする

### 説明

function 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_equals

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

hash_equals — タイミング攻撃に対しても安全な文字列比較

### 説明

function 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_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_file — ファイルの内容から、ハッシュ値を生成する

### 説明

function 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 に設定されていた場合は、メッセージダイジェストが そのままのバイナリ形式で返されます。 失敗した場合に `false` を返します

### 変更履歴

バージョン | 説明
--- | ---
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_final

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_final — 段階的なハッシュ処理を終了し、出来上がったダイジェストを返す

### 説明

function 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() - アクティブなハッシュコンテキストに、ファイルからデータを投入する

# hash_hkdf

(PHP 7 >= 7.1.2, PHP 8)

hash_hkdf — 与えられたキーから導出されるHKDFキーを生成する

### 説明

function 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` が発生していました。

### 例

上の例は、AES-256 encryption と SHA-256 authentication をそれぞれ使い、 encrypt-then-HMAC を生成する用途に合った、 異なるキーペアを生成します。

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

### 参考

- hash_pbkdf2() - PBKDF2 を使ってパスワードからキーを生成する
- » RFC 5869
- » userland implementation

# hash_hmac

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_hmac — HMAC 方式を使用してハッシュ値を生成する

### 説明

function 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` を返し、 `E_WARNING` メッセージを発行していました。
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_algos

(PHP 7 >= 7.2.0, PHP 8)

hash_hmac_algos — hash_hmac に合うハッシュアルゴリズムの一覧を返す

### 説明

function 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() - 登録されているハッシュアルゴリズムの一覧を返す

# hash_hmac_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_hmac_file — HMAC 方式を使用して、指定されたファイルの内容からハッシュ値を生成する

### 説明

function 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` を返し、 `E_WARNING` メッセージを発行していました。
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_init

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_init — 段階的なハッシュコンテキストを初期化する

### 説明

function 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 がスローされます。
- `options` に渡す設定値に型の誤りがあった場合 `E_DEPRECATED` が発生するようになりました。 予期しない解釈が行われる可能性があるためです。 これは将来 ValueError になる予定です。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 誤った型のオプションを渡すことは非推奨となりました。
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() - 段階的なハッシュ処理を終了し、出来上がったダイジェストを返す

# hash_pbkdf2

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

hash_pbkdf2 — PBKDF2 を使ってパスワードからキーを生成する

### 説明

function 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` の場合、 これは導出鍵のバイト長の二倍になります (キーの全バイトが十六進二桁で返されるからです)。

  `0`が渡された場合、与えられたアルゴリズムの出力全体が使われます。

`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_update

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update — アクティブなハッシュコンテキストにデータを投入する

### 説明

function hash_update(HashContext `$context`, string `$data`): true

### パラメータ

`context`

  hash_init() が返すハッシュコンテキスト。

`data`

  ハッシュダイジェストに含めるメッセージ。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 戻り値の型が bool ではなく true になりました。
7.2.0 | リソースの代わりに HashContext を受け入れるようになりました。

### 参考

- hash_init() - 段階的なハッシュコンテキストを初期化する
- hash_update_file() - アクティブなハッシュコンテキストに、ファイルからデータを投入する
- hash_update_stream() - アクティブなハッシュコンテキストに、オープンしているストリームから データを投入する
- hash_final() - 段階的なハッシュ処理を終了し、出来上がったダイジェストを返す

# hash_update_file

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update_file — アクティブなハッシュコンテキストに、ファイルからデータを投入する

### 説明

function 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_stream

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL hash >= 1.1)

hash_update_stream — アクティブなハッシュコンテキストに、オープンしているストリームから データを投入する

### 説明

function 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_final() - 段階的なハッシュ処理を終了し、出来上がったダイジェストを返す

## 目次

- 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 — アクティブなハッシュコンテキストに、オープンしているストリームから データを投入する

- インストール/設定
  - インストール手順
  - リソース型
- 定義済み定数
- HashContext — HashContext クラス
  - HashContext::__construct — private なコンストラクタのため、直接インスタンス化できません
  - HashContext::__debugInfo — ハッシュコンテキストに関するデバッグ情報を返す
  - 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 — アクティブなハッシュコンテキストに、オープンしているストリームから データを投入する

# Mcrypt

# はじめに

警告

この機能は 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 です。

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定
- リソース型

## 要件

ここで示す関数は、» 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() を参照ください。

## リソース型

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

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

### 説明

function 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() - 暗号学的にセキュアな、ランダムなバイト列を生成する

# 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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function 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() - 指定したパラメータでプレーンテキストを暗号化する

# 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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function 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

# 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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

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

# 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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function mcrypt_enc_get_iv_size(resource `$td`): int

この関数は、暗号化記述子で指定したアルゴリズムの iv の大きさを バイト単位で返します。IV は、cbc、cfb、ofbモード およびストリームモードのいくつかのアルゴリズムで使用されます。

### パラメータ

`td`
  暗号化記述子。

### 戻り値

この関数は、暗号化記述子で指定したアルゴリズムの iv の大きさを バイト単位で返します。 この関数が '0' を返す場合、IV は そのアルゴリズムでは無視されます。

# 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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function mcrypt_enc_get_key_size(resource `$td`): int

そのアルゴリズムでサポートされる最大キー長をバイト単位で返します。

### パラメータ

`td`
  暗号化記述子。

### 戻り値

そのアルゴリズムでサポートされる最大キー長をバイト単位で返します。

# 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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function 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_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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function 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_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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function mcrypt_enc_is_block_algorithm(resource `$td`): bool

オープンされたモードの暗号がブロックアルゴリズムであるかどうかを調べます。

### パラメータ

`td`
  暗号化記述子。

### 戻り値

アルゴリズムがブロックアルゴリズムである場合に `true`、 ストリームアルゴリズムである場合に `false` を返します。

# 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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function mcrypt_enc_is_block_algorithm_mode(resource `$td`): bool

オープンされているモードがブロックモードで動作するかどうかを調べます (たとえばストリームでは `false`、cbc や cfb、ofb では `true`)。

### パラメータ

`td`
  暗号化記述子。

### 戻り値

モードがブロックアルゴリズムを使用している場合に `true`、 その他の場合に `false` を返します。

# 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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function mcrypt_enc_is_block_mode(resource `$td`): bool

オープンされたモードがブロック出力を行うかどうかを調べます (例: cbc と ecb の場合に `true`、cfb と stream の場合に `false`)。

### パラメータ

`td`
  暗号化記述子。

### 戻り値

バイトブロックを出力するモードの場合に `true`、 バイト出力を行うモードの場合に `false` を返します。

# 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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function mcrypt_enc_self_test(resource `$td`): int

この関数は、記述子 `td` で指定したアルゴリズムの セルフテストを実行します。

### パラメータ

`td`
  暗号化記述子。

### 戻り値

成功したときは `0` を返し、 失敗したときは負の int を返します。

# 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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function 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_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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function 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_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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function mcrypt_generic_deinit(resource `$td`): bool

この関数は、暗号化記述子(`td`)で指定した 暗号化を終了します。すべてのバッファを消去しますが、モジュールは 閉じません。mcrypt_module_close() をコールする 必要があります(しかし、スクリプトの終了時に PHP が自動でこれを 行います)。

### パラメータ

`td`
  暗号化記述子。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- mcrypt_module_open() - 使用するアルゴリズムおよびモードのモジュールをオープンする
- mcrypt_generic_init() - 暗号化に必要な全てのバッファを初期化する

# 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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function 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_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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function mcrypt_get_block_size(int `$cipher`): int|false
function 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_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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function mcrypt_get_cipher_name(int `$cipher`): string
function 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

# 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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function 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_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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function mcrypt_get_key_size(int `$cipher`): int|false
function 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_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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function 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_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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function 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_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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function mcrypt_module_close(resource `$td`): bool

指定した暗号化ハンドルを閉じます。

### パラメータ

`td`
  暗号化記述子。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- mcrypt_module_open() - 使用するアルゴリズムおよびモードのモジュールをオープンする

# 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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function mcrypt_module_get_algo_block_size(string `$algorithm`, string `$lib_dir` = ?): int

指定したアルゴリズムのブロック長を取得します。

### パラメータ

`algorithm`
  アルゴリズム名。
`lib_dir`
  オプションのパラメータで、 システム上でのモードモジュールの位置を指定することが可能です。

### 戻り値

指定したアルゴリズムでサポートされるブロック長をバイト単位で返します。

# 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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function mcrypt_module_get_algo_key_size(string `$algorithm`, string `$lib_dir` = ?): int

オープンされたモードでサポートされる最大キー長を取得します。

### パラメータ

`algorithm`
  アルゴリズム名。
`lib_dir`
  オプションのパラメータで、 システム上でのモードモジュールの位置を指定することが可能です。

### 戻り値

この関数は、指定したアルゴリズムでサポートされる最大キー長をバイト単位で返します。

# 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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function 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_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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function 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_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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function 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_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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function 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_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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function 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_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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

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

# 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 で削除 されました。この関数に頼らないことを強く推奨します。

### 説明

function 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() - 暗号化モジュールを終了する

## 目次

- 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 — データを復号する

- インストール/設定
  - 要件
  - インストール手順
  - 実行時設定
  - リソース型
- 定義済み定数
- 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 — データを復号する

# Mhash

# はじめに

以下の関数は、» 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() や関連する機能でも報告されません。

# インストール/設定

## 目次

- 要件
- インストール手順

## 要件

mhash を使用するには、mhash の配布ファイルを » mhash の Web サイト から ダウンロードし、その中のインストール用の指示に従ってください。

## インストール手順

この拡張モジュールを使用するには、PHP に --with-mhash[=DIR] パラメータを付けて コンパイルする必要があります。DIR は mhash インストールディレクトリです。

PHP 5.3.0 以降では、 Hash 拡張モジュールが mhash 拡張モジュールの動作をエミュレートするようになりました。 そのため、mhash インストールディレクトリの指定は無意味となりました。 また、hash 拡張モジュールで mhash サポートを有効にしておく必要があります。

# 定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

以下に現在 mhash によりサポートされているハッシュの一覧を示します。 このリストにないけれでも mhash のドキュメントでは「サポートされている」というハッシュがある場合は このドキュメントが古いと考えてください。

`MHASH_ADLER32` (int)
`MHASH_CRC32` (int)
`MHASH_CRC32B` (int)
`MHASH_CRC32C` (int)
  PHP 7.4.0 以降で利用可能です。
`MHASH_FNV132` (int)
`MHASH_FNV1A32` (int)
`MHASH_FNV164` (int)
`MHASH_FNV1A64` (int)
`MHASH_GOST` (int)
`MHASH_HAVAL128` (int)
`MHASH_HAVAL160` (int)
`MHASH_HAVAL192` (int)
`MHASH_HAVAL224` (int)
`MHASH_HAVAL256` (int)
`MHASH_JOAAT` (int)
`MHASH_MD2` (int)
`MHASH_MD4` (int)
`MHASH_MD5` (int)
`MHASH_MURMUR3A` (int)
  PHP 8.1.0 以降で利用可能です。
`MHASH_MURMUR3C` (int)
  PHP 8.1.0 以降で利用可能です。
`MHASH_MURMUR3F` (int)
  PHP 8.1.0 以降で利用可能です。
`MHASH_RIPEMD128` (int)
`MHASH_RIPEMD160` (int)
`MHASH_RIPEMD256` (int)
`MHASH_RIPEMD320` (int)
`MHASH_SHA1` (int)
`MHASH_SHA224` (int)
`MHASH_SHA256` (int)
`MHASH_SHA384` (int)
`MHASH_SHA512` (int)
`MHASH_SNEFRU256` (int)
`MHASH_TIGER` (int)
`MHASH_TIGER128` (int)
`MHASH_TIGER160` (int)
`MHASH_WHIRLPOOL` (int)
`MHASH_XXH32` (int)
`MHASH_XXH64` (int)
`MHASH_XXH3` (int)
`MHASH_XXH128` (int)

# 例

例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

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash — ハッシュ値を計算する

警告

この関数は PHP 8.1.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function 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 になりました。

# mhash_count

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash_count — 利用可能なハッシュ ID の最大値を得る

警告

この関数は PHP 8.1.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function 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_get_block_size

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash_get_block_size — 指定したハッシュのブロックサイズを得る

警告

この関数は PHP 8.1.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function 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_hash_name

(PHP 4, PHP 5, PHP 7, PHP 8)

mhash_get_hash_name — 指定したハッシュの名前を得る

警告

この関数は PHP 8.1.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function 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_keygen_s2k

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

mhash_keygen_s2k — キーを生成する

警告

この関数は PHP 8.1.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function 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_*()` 関数 を代わりに使って下さい。

## 目次

- mhash — ハッシュ値を計算する
- mhash_count — 利用可能なハッシュ ID の最大値を得る
- mhash_get_block_size — 指定したハッシュのブロックサイズを得る
- mhash_get_hash_name — 指定したハッシュの名前を得る
- mhash_keygen_s2k — キーを生成する

- インストール/設定
  - 要件
  - インストール手順
- 定義済み定数
- 例
- Mhash 関数
  - mhash — ハッシュ値を計算する
  - mhash_count — 利用可能なハッシュ ID の最大値を得る
  - mhash_get_block_size — 指定したハッシュのブロックサイズを得る
  - mhash_get_hash_name — 指定したハッシュの名前を得る
  - mhash_keygen_s2k — キーを生成する

# OpenSSL

# はじめに

この拡張モジュールは、対称鍵による暗号化、非対称鍵による暗号化や、 PBKDF2, PKCS7, PKCS12, X509 その他の暗号の操作を行う » OpenSSL ライブラリの機能をバインドしています。 それに加えて、TLS ストリームの実装も提供しています。

この拡張モジュールではまだサポートされていない機能が 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 が必要です。 PHP >= 8.4 の場合、OpenSSL >= 1.1.1 かつ < 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 を変更させないようにしてください。

> Windows 版の PHP 8.2.0 以降でデフォルトとなっている OpenSSL 3.0.0 以降、 いくつかのアルゴリズムがレガシーとみなされるようになっています。 そうしたアルゴリズムは、暗号のコミュニティは使わなくなってきており、 かつセキュアでないと見なされてきているものです。 これらのアルゴリズムはレガシープロバイダ (extras/ssl/legacy.dll) で利用できます。その使い方は OpenSSL マニュアルの » provider configuration で説明されています。

### 変更履歴

バージョン | 説明
--- | ---
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` |
openssl.libctx | "custom" | `INI_PERDIR` |

INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

`openssl.cafile` string

  ローカルファイルシステム上の証明書ファイルの場所。 `verify_peer` コンテキストオプションで リモートサーバーとの認証の際に使用します。

`openssl.capath` string

  `cafile` が指定されていなかったりその場所にファイルが 見つからなかったりした場合、`capath` が指す ディレクトリを検索して認証ファイルを探します。`capath` は認証ファイルのディレクトリを正確に指している必要があります。

`openssl.libctx` string
  使用する OpenSSL ライブラリのコンテキストタイプを指定します。 デフォルト値は `custom` で、 ワーカーやスレッドごとに異なるライブラリコンテキストを作成します。 これにより、OpenSSL を使用している他のライブラリとの分離が促進され、 ZTS ビルドでは、スレッド間での分離も進みます。 `default` という値も指定できますが、 この場合、 PHP が OpenSSL のグローバルなデフォルトのライブラリのコンテキストを使います。

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)
`X509_PURPOSE_OCSP_HELPER` (int)
  OCSP レスポンダのヘルパーとして利用できるか証明書を検証します。 PHP 8.4.0 以降で利用可能です。
`X509_PURPOSE_TIMESTAMP_SIGN` (int)
  信頼されたタイムスタンプの署名者として利用できるか証明書を検証します。 PHP 8.4.0 以降で利用可能です。

## 非対称暗号化のパディングフラグ

`OPENSSL_PKCS1_PADDING` (int)
`OPENSSL_SSLV23_PADDING` (int)
`OPENSSL_NO_PADDING` (int)
`OPENSSL_PKCS1_OAEP_PADDING` (int)

## キーの種類

`OPENSSL_KEYTYPE_RSA` (int)
  RSA 鍵タイプ
`OPENSSL_KEYTYPE_DSA` (int)
  DSA 鍵タイプ
`OPENSSL_KEYTYPE_DH` (int)
  DH (Diffie-Hellman) 鍵タイプ
`OPENSSL_KEYTYPE_EC` (int)
  Elliptic curve (EC) 鍵タイプ
`OPENSSL_KEYTYPE_X25519` (int)
  X25519 curve 鍵タイプ。 この定数が使えるのは、PHP をコンパイルする際に OpenSSL 3.0以降を使ったときだけです。
`OPENSSL_KEYTYPE_ED25519` (int)
  Ed25519 curve 鍵タイプ。 この定数が使えるのは、PHP をコンパイルする際に OpenSSL 3.0以降を使ったときだけです。
`OPENSSL_KEYTYPE_X448` (int)
  X448 curve 鍵タイプ。 この定数が使えるのは、PHP をコンパイルする際に OpenSSL 3.0以降を使ったときだけです。
`OPENSSL_KEYTYPE_ED448` (int)
  Ed448 curve 鍵タイプ。 この定数が使えるのは、PHP をコンパイルする際に OpenSSL 3.0以降を使ったときだけです。

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

## バージョン定数

`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

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

openssl_cipher_iv_length — 初期化ベクトル iv の長さを取得する

### 説明

function 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_key_length

(PHP 8 >= 8.2.0)

openssl_cipher_key_length — 暗号鍵の長さを取得する

### 説明

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

# openssl_cms_decrypt

(PHP 8)

openssl_cms_decrypt — CMS メッセージを復号化する

### 説明

function 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` を返します。

# openssl_cms_encrypt

(PHP 8)

openssl_cms_encrypt — CMS メッセージを暗号化する

### 説明

function openssl_cms_encrypt(
string `$input_filename`,
string `$output_filename`,
OpenSSLCertificate|array|string `$certificate`,
?array `$headers`,
int `$flags` = 0,
int `$encoding` = `OPENSSL_ENCODING_SMIME`,
string|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.5.0 | `cipher_algo` の型が int または string になりました。 これより前のバージョンでは、int でした。
8.1.0 | デフォルトの暗号化アルゴリズム (`cipher_algo`) が、 AES-128-CBC (`OPENSSL_CIPHER_AES_128_CBC`) になりました。 これより前のバージョンでは、 PKCS7/CMS (`OPENSSL_CIPHER_RC2_40`) が使われていました。

# openssl_cms_read

(PHP 8)

openssl_cms_read — CMS ファイルを、PEM証明書の配列にエクスポートする

### 説明

function openssl_cms_read(string `$input_filename`, array `&$certificates`): bool

openssl_pkcs7_read() と似た処理を行います。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`input_filename`

`certificates`

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

# openssl_cms_sign

(PHP 8)

openssl_cms_sign — ファイルに署名する

### 説明

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

# openssl_cms_verify

(PHP 8)

openssl_cms_verify — CMS の署名を検証する

### 説明

function 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` を返します。

# openssl_csr_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_export — CSR を文字列としてエクスポートする

### 説明

function 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 に他の証明書（あるいは自分自身）で署名して証明書を作成する

# openssl_csr_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_export_to_file — CSR をファイルにエクスポートする

### 説明

function 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 に他の証明書（あるいは自分自身）で署名して証明書を作成する

# openssl_csr_get_public_key

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_csr_get_public_key — CSR の公開鍵を返す

### 説明

function 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() - エクスポート可能な形式で、キーを文字列に取得する

# openssl_csr_get_subject

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_csr_get_subject — CSR の subject を返す

### 説明

function 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`

  `short_names` は、配列でデータがどのように インデックスされるかを制御します - `short_names` が `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 証明書をパースし、配列として情報を返す

# openssl_csr_new

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_new — CSR を作成する

### 説明

function openssl_csr_new(
array `$distinguished_names`,
#[\SensitiveParameter] ?OpenSSLAsymmetricKey `&$private_key`,
?array `$options` = `null`,
?array `$extra_attributes` = `null`
): OpenSSLCertificateSigningRequest|bool

openssl_csr_new() は、新しい CSR を `distinguished_names` の情報に基づいて作成します。

> 注意: この関数を正しく動作させるには、正しい形式の openssl.cnf をインストールしておく必要があります。 詳細な情報は、インストールについてのセクション を参照ください。

### パラメータ

`distinguished_names`

  証明書に含まれる識別名 (Distinguished Name; DN)、または subject フィールド。 `distinguished_names` は、 キーが識別名 (DN) の属性名で、値が文字列 (単一の値の場合) ないし 配列 (複数の値を指定する必要がある場合) であるような連想配列です。

`private_key`

  `private_key` には、事前に openssl_pkey_new() （あるいはその他の openssl_pkey 系の関数）で作成した秘密鍵を設定します。 `null` も指定できます。`null` を指定した場合、 新しい秘密鍵が `options` の指定に基づいて生成され、指定された変数に代入されます。 これに対応する公開鍵が、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 へ 追加の属性を設定するために使用します。これは連想配列で、 キーを OID に変換して CSR の属性として適用されます。

### 戻り値

成功した場合、CSR を返します。 CSR の作成に成功したものの、署名に失敗した場合は `true` を返します。 失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `distinguished_names` の連想配列は、配列を値としてサポートするようになりました。 これにより、単一の属性に対して複数の値を指定できるようになりました。
8.4.0 | `extra_attributes` 引数は、CSR の属性を正しく設定するようになりました。 これまでは、subject の識別名を誤って変更してしまっていました。
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 に他の証明書（あるいは自分自身）で署名して証明書を作成する

# openssl_csr_sign

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_csr_sign — CSR に他の証明書（あるいは自分自身）で署名して証明書を作成する

### 説明

function 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 です。

`serial_hex`

  発行される証明書のシリアル番号を十六進数で表記した文字列を、 オプションで指定します。この引数を指定した場合、 `serial` 引数の値よりも優先されます。 省略したり `null` を指定したりした場合は、 `serial` 引数の値が代わりに使用されます。

### 戻り値

成功した場合に OpenSSLCertificate オブジェクト。 失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 新しい引数 `serial_hex` が追加されました。
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_decrypt

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_decrypt — データを復号する

### 説明

function 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`

  パスフレーズ。 期待した長さより短かった場合は、 黙って`NUL` 文字で埋められます。 期待した長さより長かった場合は、 黙って切り詰められます。

  警告

  `passphrase` は、 その名前から連想されるような安全な鍵生成機能は内包していません。 唯一行う操作は、期待する鍵長と異なる場合に `NUL` で パディングしたり、切り詰めたりするだけです。

`options`

  `OPENSSL_RAW_DATA`, `OPENSSL_ZERO_PADDING`, `OPENSSL_DONT_ZERO_PAD_KEY` のいずれか。

`iv`

  `null` ではない初期化ベクトル。 IV が期待するものよりも短い場合は、 `NUL` 文字でパディングされ、警告が発生します。 パスフレーズが期待するものよりも長い場合は、 切り捨てられ、警告が発生します。

`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() - データを暗号化する

# openssl_dh_compute_key

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_dh_compute_key — ローカルのDH秘密鍵とリモート側のDH公開鍵を使い、共有シークレットを計算する

### 説明

function openssl_dh_compute_key(string `$public_key`, #[\SensitiveParameter] OpenSSLAsymmetricKey `$private_key`): string|false

openssl_dh_compute_key() 関数が返す共有シークレットは、 リモート側と秘密の通信をするための暗号鍵としてよく使われます。 これはディフィー・ヘルマン鍵共有として知られています。

警告

リモートとローカルのキーペアに同じ DH パラメータを使用することが重要です。 そうしないと、両者の間で生成されたシークレットが一致しなくなります。

> 注意: 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_digest

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_digest — ダイジェストを計算する

### 説明

function 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_encrypt

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_encrypt — データを暗号化する

### 説明

function 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` 文字で埋められます。 期待した長さより長かった場合は、 黙って切り詰められます。

  警告

  `passphrase` は、 その名前から連想されるような安全な鍵生成機能は内包していません。 唯一行う操作は、期待する鍵長と異なる場合に `NUL` で パディングしたり、切り詰めたりするだけです。

`options`

  `OPENSSL_RAW_DATA`, `OPENSSL_ZERO_PADDING`, `OPENSSL_DONT_ZERO_PAD_KEY` とのビット OR。

`iv`

  `null` ではない初期化ベクトル。 IV が期待するものよりも短い場合は、 `NUL` 文字でパディングされ、警告が発生します。 パスフレーズが期待するものよりも長い場合は、 切り捨てられ、警告が発生します。

`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_error_string

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_error_string — OpenSSL エラーメッセージを返す

### 説明

function 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_free_key

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_free_key — キーリソースを開放する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function openssl_free_key(OpenSSLAsymmetricKey `$key`): void

openssl_free_key() は、指定した `key` が指すキーをメモリから開放します。

### パラメータ

`key`

### 戻り値

値を返しません。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | この関数は推奨されなくなりました。 なぜなら、実行してもなんの効果もないからです。
8.0.0 | `key` は、 OpenSSLAsymmetricKey クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 `OpenSSL key` 型のリソースを受け入れていました。

# openssl_get_cert_locations

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_get_cert_locations — 有効な証明書の格納場所を検索する

### 説明

function 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_cipher_methods

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_get_cipher_methods — 利用可能な暗号メソッドを取得

### 説明

function 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() - 利用可能なダイジェスト・メソッドを取得

# openssl_get_curve_names

(PHP 7 >= 7.1.0, PHP 8)

openssl_get_curve_names — ECC で利用可能な楕円曲線の名前を取得する

### 説明

function 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_md_methods

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_get_md_methods — 利用可能なダイジェスト・メソッドを取得

### 説明

function 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_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_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_open

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_open — シール(暗号化)されたデータをオープン(復号)する

### 説明

function 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() は、 `private_key` を使用して `encrypted_key` から復号されたエンベロープキーによって `data` をオープン(復号)します。 復号は `cipher_algo` と `iv` を使用して行なわれます。 IV は暗号方式が要求する場合にのみ必要です。復号されたデータは `output` に 格納されます。エンベロープキーは通常、秘密鍵に関連付けられた公開鍵を用いてデータがシール(暗号化) されたときに生成されます。 詳細は openssl_seal() を参照ください。

### パラメータ

`data`

  シール(暗号化)されたデータ。

`output`

  成功した場合、オープンしたデータをこのパラメータに格納して返します。

`encrypted_key`

  `private_key` を用いて復号できる暗号化された対称鍵。

`private_key`

  `encrypted_key`の復号に用いられる秘密鍵。

`cipher_algo`

  `data`の復号に使用される暗号化方式。

  警告

  PHP 8.0 より前のデフォルト値 (`'RC4'`) は安全ではありません。 明示的にセキュアな暗号化方式を指定することを強く推奨します。

`iv`

  `data`の復号に用いられる初期化ベクトル。暗号方式が IV を要求する場合に必要です。 これは `cipher_algo` で openssl_cipher_iv_length() を呼び出すことで確認できます。

### 戻り値

成功した場合に `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 および $iv に暗号化されたデータおよびエンベロープキーと
    // IV が含まれていると仮定。すべてシール元(暗号化側)から与えられる。

    // private_key.pem に置かれたファイルから秘密鍵を取得する
    $pkey = openssl_get_privatekey("file://private_key.pem");

    // データを復号化し、$open に保存
    if (openssl_open($sealed, $open, $env_key, $pkey, 'AES256', $iv)) {
        echo "Here is the opened data: ", $open;
    } else {
        echo "Failed to open data";
    }
    ?>

### 参考

- openssl_seal() - データをシール(暗号化)する

# openssl_password_hash

(PHP 8 >= 8.4.0)

openssl_password_hash — OpenSSL の Argon2 実装を使ってパスワードハッシュを作る

### 説明

function openssl_password_hash(string `$algo`, string `$password`, array `$options` = []): string

OpenSSL の Argon2 実装を使ってパスワードハッシュを作ります。 この関数は、バックエンドとして OpenSSL を使う password_hash() の代替手段であり、 プラットフォームによってはハードウェアアクセラレーションを利用できます。

この関数は、PHP が Argon2 をサポートする OpenSSL (`HAVE_OPENSSL_ARGON2`) とともにコンパイルされている場合にのみ使用できます。

### パラメータ

`algo`

  パスワードハッシュアルゴリズム。サポートされている値は `"argon2id"` と `"argon2i"` です。

`password`

  ユーザーのパスワード。

`options`

  オプションの連想配列 (array)。サポートされるキーは以下のとおりです:

  - `memory_cost` - ハッシュの計算に使用する 最大メモリ量 (KiB 単位)
  - `time_cost` - ハッシュの計算にかける 最大時間
  - `threads` - ハッシュの計算に使用する スレッド数

### 戻り値

パスワードハッシュを文字列 (string) で返します。

### エラー / 例外

`algo` がサポートされている値 (`"argon2i"` または `"argon2id"`) のいずれでもない場合、ValueError をスローします。

不明な原因でハッシュ操作が失敗した場合、 Error をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 関数が追加されました。

### 例

例1 openssl_password_hash() の例

    <?php
    $hash = openssl_password_hash('argon2id', 'my-secret-password');
    echo $hash;
    ?>

上の例の出力は、 たとえば以下のようになります。

    $argon2id$v=19$m=65536,t=4,p=1$c29tZXNhbHR2YWx1ZQ$hashvalue...

例2 カスタムオプションを指定した openssl_password_hash() の例

    <?php
    $hash = openssl_password_hash('argon2id', 'my-secret-password', [
        'memory_cost' => 65536,
        'time_cost'   => 4,
        'threads'     => 1,
    ]);
    ?>

### 参考

- openssl_password_verify() - OpenSSL の Argon2 実装を用いてパスワードをハッシュと照合する
- password_hash() - パスワードハッシュを作る

# openssl_password_verify

(PHP 8 >= 8.4.0)

openssl_password_verify — OpenSSL の Argon2 実装を用いてパスワードをハッシュと照合する

### 説明

function openssl_password_verify(string `$algo`, string `$password`, string `$hash`): bool

パスワードが openssl_password_hash() で作成したハッシュにマッチするかどうかを検証します。

この関数は、PHP が Argon2 をサポートする OpenSSL (`HAVE_OPENSSL_ARGON2`) とともにコンパイルされている場合にのみ使用できます。

### パラメータ

`algo`

  パスワードハッシュアルゴリズム。サポートされている値は `"argon2id"` と `"argon2i"` です。

`password`

  ユーザーのパスワード。

`hash`

  openssl_password_hash() で作成したハッシュ。

### 戻り値

パスワードとハッシュがマッチする場合に `true`、それ以外の場合に `false` を返します。

### エラー / 例外

`algo` がサポートされている値 (`"argon2i"` または `"argon2id"`) のいずれでもない場合、ValueError をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 関数が追加されました。

### 例

例1 openssl_password_verify() の例

    <?php
    $hash = openssl_password_hash('argon2id', 'my-secret-password');

    if (openssl_password_verify('argon2id', 'my-secret-password', $hash)) {
        echo 'Password matches.';
    } else {
        echo 'Password does not match.';
    }
    ?>

### 参考

- openssl_password_hash() - OpenSSL の Argon2 実装を使ってパスワードハッシュを作る
- password_verify() - パスワードがハッシュにマッチするかどうかを調べる

# openssl_pbkdf2

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

openssl_pbkdf2 — PKCS5 v2 の PBKDF2 文字列を生成する

### 説明

function 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 は、暗号化のソルトとして、少なくとも128ビット(16バイト)を推奨しています。
`key_length`

  出力されるキーの長さ

`iterations`

  反復回数。 » NIST は最低でも1000を推奨しています。 2023 年の時点で、OWASP は PBKDF2-HMAC-SHA256 に対して 600,000 回、 PBKDF2-HMAC-SHA512 に対して 210,000 回の反復を推奨しています。

`digest_algo`

  オプションのハッシュまたはダイジェストアルゴリズム。 アルゴリズムの一覧は、openssl_get_md_methods() で得られます。 デフォルトは SHA-1 ですが、SHA-256 または SHA-512 を推奨しています。

### 戻り値

生のバイナリ文字列を返します。失敗した場合に `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() - 利用可能なダイジェスト・メソッドを取得

# openssl_pkcs12_export

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_export — PKCS#12 互換の証明書保存ファイルを変数にエクスポートする

### 説明

function 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` で指定した文字列に格納します。

### パラメータ

`certificate`
  使用できる値の一覧は キー/証明書パラメータ を参照ください。
`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` 型のリソースを受け入れていました。

# openssl_pkcs12_export_to_file

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_export_to_file — PKCS#12 互換の証明書保存ファイルをエクスポートする

### 説明

function 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 フォーマットで保存します。

### パラメータ

`certificate`
  使用できる値の一覧は キー/証明書パラメータ を参照ください。
`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` 型のリソースを受け入れていました。

# openssl_pkcs12_read

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

openssl_pkcs12_read — PKCS#12 認証ストアをパースして配列形式にする

### 説明

function 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;
    }
    ?>

# openssl_pkcs7_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_decrypt — S/MIME 暗号化されたメッセージを復号する

### 説明

function 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 "復号に失敗しました!";
    }
    ?>

# openssl_pkcs7_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_encrypt — S/MIME メッセージを暗号化する

### 説明

function 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");
    }
    ?>

# openssl_pkcs7_read

(PHP 7 >= 7.2.0, PHP 8)

openssl_pkcs7_read — PKCS7 ファイルを PEM証明書 の配列にエクスポートする

### 説明

function 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 に他の証明書（あるいは自分自身）で署名して証明書を作成する

# openssl_pkcs7_sign

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_sign — S/MIME メッセージに署名する

### 説明

function 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");
    }
    ?>

# openssl_pkcs7_verify

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_pkcs7_verify — S/MIME で署名されたメッセージの署名を検証する

### 説明

function 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 文字より長くなってはいけません。

# openssl_pkey_derive

(PHP 7 >= 7.3.0, PHP 8)

openssl_pkey_derive — リモートとローカルの DH/ECDH鍵 の公開値のための、共有シークレットを計算する

### 説明

function 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でない場合、生成するシークレットの長さを設定しようと試みます。

  警告

  このパラメータは非推奨になっているため、使用しないでください。 なぜなら、期待どおりに機能しないためです。 シークレットが素数のサイズよりも長くなることはありません。 必要な長さが素数のサイズより小さい場合、ECDH キーの場合のみ長さを切り詰めますが、 DH キーの場合は失敗します。

### 戻り値

成功時には、生成されたシークレットを返します。 失敗した場合に `false` を返します.

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | `key_length` は、推奨されなくなりました。

### 例

例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_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_export — エクスポート可能な形式で、キーを文字列に取得する

### 説明

function 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_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_export_to_file — エクスポート可能な形式で、キーをファイルに取得する

### 説明

function 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_free

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_free — 秘密鍵を開放する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function 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_get_details

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

openssl_pkey_get_details — キーの詳細の配列を返す

### 説明

function 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`, `OPENSSL_KEYTYPE_X25519`, `OPENSSL_KEYTYPE_ED25519`, `OPENSSL_KEYTYPE_X448`, `OPENSSL_KEYTYPE_ED448` のいずれか。 あるいは不明な場合は `-1`) となります。

使っているキーの種類によって、さらに詳細が返されます。 常に存在するわけではない要素もあることに注意しましょう。

- `OPENSSL_KEYTYPE_RSA` の場合は `"rsa"` というキーがあり、キーのデータが返されます。

  Key | 説明
  --- | ---
  `"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"` というキーがあり、キーのデータが返されます。

  Key | 説明
  --- | ---
  `"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"` というキーがあり、キーのデータが返されます。

  Key | 説明
  --- | ---
  `"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_X25519`, `OPENSSL_KEYTYPE_ED25519`, `OPENSSL_KEYTYPE_X448`, `OPENSSL_KEYTYPE_ED448` の場合は、 `"x25519"`, `"ed25519"`, `"x448"`, `"ed448"` というキーがそれぞれあり、 キーのデータが返されます。

  Key | 説明
  --- | ---
  `"priv_key"` | private key
  `"pub_key"` | public key

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | Curve25519 と Curve448 ベースの鍵のサポートが追加されました。 `x25519`, `ed25519`, `x448`, `ed448` という連想配列のフィールドが新たに導入されています。
8.0.0 | `key` は、 OpenSSLAsymmetricKey クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 `OpenSSL key` 型のリソースを受け入れていました。

# openssl_pkey_get_private

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_get_private — 秘密鍵を取得する

### 説明

function 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_public

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_get_public — 証明書から公開鍵を抽出し、使用できるようにする

### 説明

function 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_new

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_pkey_new — 新規に秘密鍵を生成する

### 説明

function openssl_pkey_new(?array `$options` = `null`): OpenSSLAsymmetricKey|false

openssl_pkey_new() は、 新しい秘密鍵を生成します。 鍵の公開部を取得する方法は、以下の例に示します。

> 注意: この関数を正しく動作させるには、正しい形式の openssl.cnf をインストールしておく必要があります。 詳細な情報は、インストールについてのセクション を参照ください。

### パラメータ

`options`

  `options` を使うと、 鍵の生成処理を微調整(例：ビット数やパラメータの指定) することができます。 これらのオプションは、鍵生成に用いられるアルゴリズム固有のパラメータ、 または指定がない場合に CSR 生成でも用いられる汎用オプションのいずれかです。 CSR に関する `options` の使用方法の詳細については、 openssl_csr_new() を参照ください。 これらのオプションのうち、鍵生成に使用されるのは `private_key_bits`, `private_key_type`, `curve_name`, `config` のみになります。 連想配列に特定のキーが含まれている場合、アルゴリズム固有のオプションが使用されます。

  - RSA パラメータを設定するためのキーは `"rsa"` です。

    options | type | format | required | description
    --- | --- | --- | --- | ---
    `"n"` | string | binary number | yes | modulus
    `"e"` | string | binary number | no | public exponent
    `"d"` | string | binary number | yes | private exponent
    `"p"` | string | binary number | no | prime 1
    `"q"` | string | binary number | no | prime 2
    `"dmp1"` | string | binary number | no | exponent1, d mod (p-1)
    `"dmq1"` | string | binary number | no | exponent2, d mod (q-1)
    `"iqmp"` | string | binary number | no | coefficient, (inverse of q) mod p

  - DSA パラメータを設定するためのキーは `"dsa"` です。

    options | type | format | required | description
    --- | --- | --- | --- | ---
    `"p"` | string | binary number | no | prime number (public)
    `"q"` | string | binary number | no | 160-bit subprime, q | p-1 (public)
    `"g"` | string | binary number | no | generator of subgroup (public)
    `"priv_key"` | string | PEM key | no | private key x
    `"pub_key"` | string | PEM key | no | public key y = g^x

  - DH (Diffie–Hellman key exchange) パラメータを設定するためのキーは `"dh"` です。

    Options | 型 | Format | Required | 説明
    --- | --- | --- | --- | ---
    `"p"` | string | binary number | no | prime number (shared)
    `"g"` | string | binary number | no | generator of Z_p (shared)
    `"priv_key"` | string | PEM key | no | private DH value x
    `"pub_key"` | string | PEM key | no | public DH value g^x

  - Elliptic curve パラメータを設定するためのキーは `"ec"` です。

    Options | 型 | Format | Required | 説明
    --- | --- | --- | --- | ---
    `"curve_name"` | string | name | no | name of curve, see openssl_get_curve_names()
    `"p"` | string | binary number | no | prime of the field for curve over Fp
    `"a"` | string | binary number | no | coofecient a of the curve for Fp: y^2 mod p = x^3 + ax + b mod p
    `"b"` | string | binary number | no | coofecient b of the curve for Fp: y^2 mod p = x^3 + ax + b mod p
    `"seed"` | string | binary number | no | optional random number seed used to generate coefficient b
    `"generator"` | string | binary encoded point | no | curve generator point
    `"g_x"` | string | binary number | no | curver generator point x coordinat
    `"g_y"` | string | binary number | no | curver generator point y coordinat
    `"cofactor"` | string | binary number | no | curve cofactor
    `"order"` | string | binary number | no | curve order
    `"x"` | string | binary number | no | x coordinate (public)
    `"y"` | string | binary number | no | y coordinate (public)
    `"d"` | string | binary number | no | private key

  - Curve25519 と Curve448 パラメータを設定するためのキーは `"x25519"`, `"x448"`, `"ed25519"`, `"ed448"` です。

    Options | 型 | Format | Required | 説明
    --- | --- | --- | --- | ---
    `"priv_key"` | string | PEM key | no | private key
    `"pub_key"` | string | PEM key | no | public key

### 戻り値

成功した場合に、OpenSSLAsymmetricKey クラスのインスタンスを返します。 エラー時に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | Curve25519 と Curve448 ベースの鍵を生成する機能がサポートされました。 使える連想配列のフィールドは `x25519`, `ed25519`, `x448`, `ed448` です。
8.3.0 | カスタムの EC パラメータを使って、 EC 鍵を生成する機能がサポートされました。 EC 鍵の生成に使うオプションを以下に示します: `p`, `a`, `b`, `seed`, `generator`, `g_x`, `g_y`, `cofactor`, `order`
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, PHP_EOL;

    $public_key = openssl_pkey_get_public($public_key_pem);
    var_dump($public_key);

    ?>

上の例の出力は、 たとえば以下のようになります。

    // Output prior to PHP 8.0.0; note, the function returns a resource
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwknBFEherZe74BiRjTFA
    hqwZ1SK7brwq7C/afnLXKhRR7jnrpfM0ypC46q8xz5UZswenZakJ7kd5fls+r4Bv
    3P8XsKYLTh2m1GiWQhV1g77cNIN4qNWh70PiDO3fB2446o1LBgToQYuRZS5YQRfJ
    rVD0ysgtVcCU9tjaey28HlgApOpYFTaaKPj2MBmEYpMC+kG2HhL12GfpHUi2eiXI
    dXT2WskWHWvUrmQ7fJIfI92JlDokV62DH/q1oiedLs9OPNb0rL1aAmYdzaVN6XNH
    x/o4Lh125v2vAPV9E3fZCDc/HDEUaahpjanMiCQEgEDp5Hr+CRkvERT5/ydN+p08
    5wIDAQAB
    -----END PUBLIC KEY-----

    resource(6) of type (OpenSSL key)

    // Output as of PHP 8.0.0; note, the function returns an object
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwknBFEherZe74BiRjTFA
    hqwZ1SK7brwq7C/afnLXKhRR7jnrpfM0ypC46q8xz5UZswenZakJ7kd5fls+r4Bv
    3P8XsKYLTh2m1GiWQhV1g77cNIN4qNWh70PiDO3fB2446o1LBgToQYuRZS5YQRfJ
    rVD0ysgtVcCU9tjaey28HlgApOpYFTaaKPj2MBmEYpMC+kG2HhL12GfpHUi2eiXI
    dXT2WskWHWvUrmQ7fJIfI92JlDokV62DH/q1oiedLs9OPNb0rL1aAmYdzaVN6XNH
    x/o4Lh125v2vAPV9E3fZCDc/HDEUaahpjanMiCQEgEDp5Hr+CRkvERT5/ydN+p08
    5wIDAQAB
    -----END PUBLIC KEY-----

    object(OpenSSLAsymmetricKey)#2 (0) {
    }

例2 RSA 鍵を生成する

    <?php

    $nhex = "BBF82F090682CE9C2338AC2B9DA871F7368D07EED41043A440D6B6F07454F51F" .
            "B8DFBAAF035C02AB61EA48CEEB6FCD4876ED520D60E1EC4619719D8A5B8B807F" .
            "AFB8E0A3DFC737723EE6B4B7D93A2584EE6A649D060953748834B2454598394E" .
            "E0AAB12D7B61A51F527A9A41F6C1687FE2537298CA2A8F5946F8E5FD091DBDCB";

    $ehex = "11";
    $dhex = "A5DAFC5341FAF289C4B988DB30C1CDF83F31251E0668B42784813801579641B2" .
            "9410B3C7998D6BC465745E5C392669D6870DA2C082A939E37FDCB82EC93EDAC9" .
            "7FF3AD5950ACCFBC111C76F1A9529444E56AAF68C56C092CD38DC3BEF5D20A93" .
            "9926ED4F74A13EDDFBE1A1CECC4894AF9428C2B7B8883FE4463A4BC85B1CB3C1";

    $phex = "EECFAE81B1B9B3C908810B10A1B5600199EB9F44AEF4FDA493B81A9E3D84F632" .
            "124EF0236E5D1E3B7E28FAE7AA040A2D5B252176459D1F397541BA2A58FB6599";

    $qhex = "C97FB1F027F453F6341233EAAAD1D9353F6C42D08866B1D05A0F2035028B9D86" .
            "9840B41666B42E92EA0DA3B43204B5CFCE3352524D0416A5A441E700AF461503";

    $dphex = "11";
    $dqhex = "11";
    $qinvhex = "b06c4fdabb6301198d265bdbae9423b380f271f73453885093077fcd39e2119f" .
               "c98632154f5883b167a967bf402b4e9e2e0f9656e698ea3666edfb25798039f7";

    $rsa= openssl_pkey_new([
        'rsa' => [
            'n' => hex2bin($nhex),
            'e' => hex2bin($ehex),
            'd' => hex2bin($dhex),
            'p' => hex2bin($phex),
            'q' => hex2bin($qhex),
            'dmp1' => hex2bin($dphex),
            'dmq1' => hex2bin($dqhex),
            'iqmp' => hex2bin($qinvhex),
        ],
    ]);
    $details = openssl_pkey_get_details($rsa);
    var_dump($details);

    ?>

# openssl_private_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_private_decrypt — 秘密鍵でデータを復号する

### 説明

function openssl_private_decrypt(
string `$data`,
#[\SensitiveParameter] string `&$decrypted_data`,
#[\SensitiveParameter] OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
int `$padding` = `OPENSSL_PKCS1_PADDING`,
?string `$digest_algo` = `null`
): 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` が指定可能です。

`digest_algo`
  OAEP パディング用のダイジェストアルゴリズム。`null` の場合はデフォルトのアルゴリズムを使用します。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | オプションのパラメータ `digest_algo` が追加されました。
8.0.0 | `private_key` は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 `OpenSSL key` または `OpenSSL X.509` 型のリソースを受け入れていました。

### 参考

- openssl_public_encrypt() - 公開鍵でデータを暗号化する
- openssl_public_decrypt() - 公開鍵でデータを復号する

# openssl_private_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_private_encrypt — 秘密鍵でデータを暗号化する

### 説明

function 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`

  `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_public_decrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_public_decrypt — 公開鍵でデータを復号する

### 説明

function 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_encrypt

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_public_encrypt — 公開鍵でデータを暗号化する

### 説明

function openssl_public_encrypt(
#[\SensitiveParameter] string `$data`,
string `&$encrypted_data`,
OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`,
int `$padding` = `OPENSSL_PKCS1_PADDING`,
?string `$digest_algo` = `null`
): bool

openssl_public_encrypt() は、`data` を公開鍵 `public_key` で暗号化し、それを `encrypted_data` に格納します。暗号化されたデータは openssl_private_decrypt() を用いて復号可能です。

この関数を使用するのは、例えば秘密鍵の所有者にのみ読めるようにメッセージを暗号化する場合です。 また、データベースに格納するデータを安全な形式にするためにも使用されます。

### パラメータ

`data`

`encrypted_data`

  暗号化した結果がここに格納されます。

`public_key`

  `public_key` は、 データの復号に使用する秘密鍵と対になる公開鍵である必要があります。

`padding`

  `padding` には `OPENSSL_PKCS1_PADDING`、 `OPENSSL_SSLV23_PADDING`、 `OPENSSL_PKCS1_OAEP_PADDING`、 `OPENSSL_NO_PADDING` が指定可能です。

`digest_algo`
  OAEP パディング用のダイジェストアルゴリズム。 デフォルトのアルゴリズムを使用する場合は `null` を指定します。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | オプションのパラメータ `digest_algo` が追加されました。
8.0.0 | `public_key` は、 OpenSSLAsymmetricKey または OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 `OpenSSL key` または `OpenSSL X.509` 型のリソースを受け入れていました。

### 参考

- openssl_private_encrypt() - 秘密鍵でデータを暗号化する
- openssl_private_decrypt() - 秘密鍵でデータを復号する

# openssl_random_pseudo_bytes

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

openssl_random_pseudo_bytes — 疑似ランダムなバイト文字列を生成する

### 説明

function 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_seal

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_seal — データをシール(暗号化)する

### 説明

function 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` 配列内の各公開鍵で暗号化され、 それぞれ暗号化されたエンベロープキーは `encrypted_keys` パラメータで返されます。 これによって、(公開鍵が利用可能なら) 複数の受信者にシールされた データを送信できます。各受信者は、シールされたデータと受信者の公開鍵で暗号化されたエンベロープキー の両方を受け取らなければいけません。 生成された IV (初期化ベクトル) は `iv` パラメータで返されます。

### パラメータ

`data`

  シールするデータ。

`sealed_data`

  シール済みのデータ。

`encrypted_keys`

  暗号化したキーの配列。

`public_key`

  公開鍵を含んだ OpenSSLAsymmetricKey クラスのインスタンスの配列。

`cipher_algo`

  暗号化方式

  警告

  PHP 8.0 より前のデフォルト値 (`'RC4'`) は安全ではありません。 明示的にセキュアな暗号化方式を指定することを強く推奨します。

`iv`

  `data`の復号に用いられる初期化ベクトル。暗号方式が IV を要求する場合に必要です。 これは `cipher_algo` で openssl_cipher_iv_length() を呼び出すことで確認できます。

  警告

  初期化ベクトルは明示的に設定できません。設定された値はランダムに生成された値で上書きされます。

### 戻り値

成功時にシール(暗号化)されたデータの長さ、エラー時に `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 には、暗号化されるデータが含まれていると仮定
    $data = "test";

    // 公開鍵を取得する
    $pk1 = openssl_get_publickey("file://cert1.pem");
    $pk2 = openssl_get_publickey("file://cert2.pem");

    // メッセージを暗号化。$pk1 および $pk2 の所有者のみが、$sealed を
    // それぞれ $ekeys[0] および $ekeys[1] で復号することが可能
    if (openssl_seal($data, $sealed, $ekeys, array($pk1, $pk2), 'AES256', $iv) > 0) {
        // $sealed と $iv の値を格納し、後で openssl_open で使用することもできます。
        echo "success\n";
    }
    ?>

### 参考

- openssl_open() - シール(暗号化)されたデータをオープン(復号)する

# openssl_sign

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_sign — 署名を生成する

### 説明

function openssl_sign(
string `$data`,
string `&$signature`,
#[\SensitiveParameter] OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$private_key`,
string|int `$algorithm` = `OPENSSL_ALGO_SHA1`,
int `$padding` = 0
): 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" など)。

`padding`
  使用する RSA PSS パディング。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | オプションのパラメータ `padding` が追加されました。
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() - 署名を検証する

# openssl_spki_export

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_export — 署名済みの公開鍵とチャレンジから、有効なPEMフォーマットの公開鍵をエクスポートする

### 説明

function 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_challenge

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_export_challenge — 署名済みの公開鍵とチャレンジに関連するチャレンジをエクスポートする

### 説明

function 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_new

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_new — 署名された公開鍵とチャレンジを新規に作成する

### 説明

function 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_verify

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_spki_verify — 署名済みの公開鍵とチャレンジを検証する

### 説明

function 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_verify

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

openssl_verify — 署名を検証する

### 説明

function openssl_verify(
string `$data`,
string `$signature`,
OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`,
string|int `$algorithm` = `OPENSSL_ALGO_SHA1`,
int `$padding` = 0
): 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" など)。

`padding`
  使用する RSA PSS パディング。

### 戻り値

署名 (signature) が正しい場合に 1、正しくない場合に 0、 エラーの場合に -1 または `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | オプションのパラメータ `padding` が追加されました。
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_x509_check_private_key

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_check_private_key — 秘密鍵が証明書に対応するかを確認する

### 説明

function 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_checkpurpose

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_checkpurpose — 証明書が特定の目的に使用可能かどうか確認する

### 説明

function 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_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_export — 証明書を文字列としてエクスポートする

### 説明

function openssl_x509_export(OpenSSLCertificate|string `$certificate`, string `&$output`, bool `$no_text` = `true`): bool

openssl_x509_export() は、 PEMエンコード形式の `certificate` を文字列 `output` に保存します。

### パラメータ

`certificate`
  使用できる値の一覧は キー/証明書パラメータ を参照ください。
`output`

  成功した場合に、ここに PEM が格納されます。

`no_text`
  オプションのパラメータ `notext` を設定すると、出力内容の冗長性が変化します。`false` を指定すると、 人間が読むための追加情報が出力に含まれるようになります。 `notext` のデフォルト値は `true` です。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `certificate` は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 `OpenSSL X.509` 型のリソースを受け入れていました。

# openssl_x509_export_to_file

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

openssl_x509_export_to_file — 証明書をファイルにエクスポートする

### 説明

function 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` に保存します。

### パラメータ

`certificate`
  使用できる値の一覧は キー/証明書パラメータ を参照ください。
`output_filename`

  出力ファイルへのパス。

`no_text`
  オプションのパラメータ `notext` を設定すると、出力内容の冗長性が変化します。`false` を指定すると、 人間が読むための追加情報が出力に含まれるようになります。 `notext` のデフォルト値は `true` です。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `certificate` は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 `OpenSSL X.509` 型のリソースを受け入れていました。

# openssl_x509_fingerprint

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

openssl_x509_fingerprint — 与えられた X.509 証明書のフィンガープリントあるいはダイジェストを計算する

### 説明

function openssl_x509_fingerprint(OpenSSLCertificate|string `$certificate`, string `$digest_algo` = "sha1", bool `$binary` = `false`): string|false

openssl_x509_fingerprint() は `certificate` のダイジェストを文字列で返します。

### パラメータ

`certificate`
  使用できる値の一覧は キー/証明書パラメータ を参照ください。
`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_free

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_free — 証明書リソースを開放する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function 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` 型のリソースを受け入れていました。

# openssl_x509_parse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_parse — X509 証明書をパースし、配列として情報を返す

### 説明

function 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.4.0 | すべての OpenSSL バージョンで、UTCTime に秒が含まれていない証明書をパースできなくなりました。 OpenSSL のバージョン 3.3 以降を使っていた場合は、以前からパースできませんでした。
8.0.0 | `certificate` は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 `OpenSSL X.509` 型のリソースを受け入れていました。

# openssl_x509_read

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

openssl_x509_read — X.509 証明書をパースし、オブジェクトを返す

### 説明

function openssl_x509_read(OpenSSLCertificate|string `$certificate`): OpenSSLCertificate|false

openssl_x509_read() は、 `certificate` で指定した証明書をパースし、 その証明書用の OpenSSLCertificate オブジェクトを返します。

### パラメータ

`certificate`

  X509 証明書。有効な値の一覧は、 Key/Certificate parameters を参照ください。

### 戻り値

成功した場合に OpenSSLCertificate オブジェクトを返します。 失敗した場合に `false` を返します

### エラー / 例外

X.509 証明書を取得できなかった場合、 `E_WARNING` レベルのエラーが発生します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | 成功した場合に、この関数は OpenSSLCertificate クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 `OpenSSL X.509` 型のリソースを返していました。
8.0.0 | `certificate` は、 OpenSSLCertificate クラスのインスタンスを受け入れるようになりました。 これより前のバージョンでは、 `OpenSSL X.509` 型のリソースを受け入れていました。

# openssl_x509_verify

(PHP 7 >= 7.4.0, PHP 8)

openssl_x509_verify — x509証明書のデジタル署名を公開鍵で検証する

### 説明

function openssl_x509_verify(OpenSSLCertificate|string `$certificate`, OpenSSLAsymmetricKey|OpenSSLCertificate|array|string `$public_key`): int

openssl_x509_verify() 関数は、 `certificate` 証明書が 公開鍵 `public_key` に対応する秘密鍵で署名されたかどうかを検証します。

### パラメータ

`certificate`
  使用できる値の一覧は キー/証明書パラメータ を参照ください。
`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 のエイリアス

## 目次

- 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_password_hash — OpenSSL の Argon2 実装を使ってパスワードハッシュを作る
- openssl_password_verify — OpenSSL の Argon2 実装を用いてパスワードをハッシュと照合する
- 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 クラス

(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 {
}

- インストール/設定
  - 要件
  - インストール手順
  - 実行時設定
  - リソース型
- 定義済み定数
  - 目的を調べるフラグ
  - 非対称暗号化のパディングフラグ
  - キーの種類
  - 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_password_hash — OpenSSL の Argon2 実装を使ってパスワードハッシュを作る
  - openssl_password_verify — OpenSSL の Argon2 実装を用いてパスワードをハッシュと照合する
  - 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 クラス

# パスワードのハッシュ

# はじめに

パスワードハッシュ API は crypt() および他のいくつかのパスワードハッシュアルゴリズムを 手軽に使えるようにしたラッパーで、 パスワードの作成や管理を安全な方法で行えます。

# インストール/設定

## 目次

- 要件
- インストール手順

## 要件

外部ライブラリは必要ありません。

Argon2 パスワードハッシュには、 » libargon2 が必要です。 PHP 8.4.0 以降では、libargon2 の代わりに OpenSSL のバージョン 3.2 以降を使うこともできます。 libargon2 を使う場合、PHP 7.3.0 以降では libargon2 バージョン 20161029 以降が必要になります。

## インストール手順

PHP コアに含まれるため、 追加のインストール無しで使用できます。

ただし、Argon2 パスワードハッシュを有効にするには、 --with-password-argon2 オプションを使用し libargon2 のサポートを有効にして PHP をビルドする必要があります。 PHP 8.4.0 以降で libargon2 の代わりに OpenSSL を使う場合、 --with-openssl と --with-openssl-argon2 オプションを使用し OpenSSL を有効にして 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() のページを参照ください。

    省略した場合のデフォルトは `12` です。この値でもかまいませんが、 ハードウェアの性能が許すならもう少し高くすることもできます。

`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` (string)

  アルゴリズムを指定しなかったときのデフォルトとして使うアルゴリズム。 PHP のバージョンが上がるときに、 その時点でより強力なハッシュアルゴリズムに対応していればデフォルトが変わる可能性があります。

  この定数の値は、今後変わる可能性があることに注意しましょう。 つまり、生成されるハッシュの長さも変わる可能性があるということです。 したがって、`PASSWORD_DEFAULT` を使う場合は、 ハッシュの格納先は任意の長さのハッシュを格納できるようにしておく必要があります。 お勧めの長さは `255` バイトです。

  現状は、`PASSWORD_BCRYPT` のエイリアスです。

##### 変更履歴

バージョン | 説明
--- | ---
7.4.0 | パスワードのアルゴリズムのID (`PASSWORD_BCRYPT`, `PASSWORD_ARGON2I`, `PASSWORD_ARGON2ID`, `PASSWORD_DEFAULT`) は、string に変更されました。 これより前のバージョンでは、int でした。

# Password Hashing 関数

# password_algos

(PHP 7 >= 7.4.0, PHP 8)

password_algos — 利用可能なパスワードハッシュアルゴリズムのIDを取得する

### 説明

function password_algos(): array

登録済みのパスワードハッシュアルゴリズムのIDの完全な一覧を、 文字列の配列として返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

利用可能なパスワードハッシュアルゴリズムのIDを返します。

### 例

例1 password_algos() の基本的な使用法

    <?php
    print_r(password_algos());
    ?>

上の例の出力は、 たとえば以下のようになります。

    Array
    (
        [0] => 2y
        [1] => argon2i
        [2] => argon2id
    )

# password_get_info

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_get_info — 指定したハッシュに関する情報を返す

### 説明

function password_get_info(string `$hash`): array

password_hash() がサポートするアルゴリズムで生成した有効なハッシュを渡すと、 そのハッシュに関する情報の配列を返します。

### パラメータ

`hash`

  password_hash() が作ったハッシュ。

### 戻り値

三つの要素を持つ連想配列を返します。

- `algo` には、そのハッシュの パスワードアルゴリズム定数 が含まれます。
- `algoName` には、そのアルゴリズムの名前が含まれます。
- `options` には、 password_hash() を呼んだときのオプションが含まれます。

# password_hash

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_hash — パスワードハッシュを作る

### 説明

function 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` - bcrypt アルゴリズムを使ってハッシュを作ります。 これは標準の crypt() 互換のハッシュで、識別子 `$2y$` を使った場合の結果を作ります。
- `PASSWORD_ARGON2I` - Argon2i ハッシュアルゴリズムを使って ハッシュを作ります。このアルゴリズムは、 PHP が Argon2 のサポートを有効にしてコンパイルした場合のみ利用できます。
- `PASSWORD_ARGON2ID` - Argon2id ハッシュアルゴリズムを使って ハッシュを作ります。このアルゴリズムは、 PHP が Argon2 のサポートを有効にしてコンパイルした場合のみ利用できます。

`PASSWORD_BCRYPT` がサポートするオプション:

- `salt` (string) - パスワードのハッシュに使うソルトを手動で設定します。 これは、自動生成されたソルトを上書きすることに注意しましょう。

  省略した場合は、パスワードをハッシュするたびに password_hash() がランダムなソルトを自動生成します。これは意図したとおりの操作モードです。

  警告

  このソルト・オプションは 非推奨になっています。 このオプションは指定せずに、デフォルトで生成されるソルトを使うことを推奨します。 PHP 8.0.0 以降は、この値を明示的に指定しても無視されます。

- `cost` (int) - 利用するアルゴリズムのコストを表します。 値の例については crypt() のページを参照ください。

  省略した場合のデフォルトは `12` です。この値でもかまいませんが、 ハードウェアの性能に応じて調整すべきです。

`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.4.0 | `PASSWORD_BCRYPT` アルゴリズムのデフォルトの `cost` オプションの値が `10` から `12` に引き上げられました。
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
    echo password_hash("rasmuslerdorf", PASSWORD_DEFAULT);
    ?>

上の例の出力は、 たとえば以下のようになります。

    $2y$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.

例2 password_hash() で、コストを手動で設定する例

    <?php
    $options = [
        // bcrypt のコストを 12 から 13 に増やします
        'cost' => 13,
    ];
    echo password_hash("rasmuslerdorf", PASSWORD_BCRYPT, $options);
    ?>

上の例の出力は、 たとえば以下のようになります。

    $2y$13$xeDfQumlmdm0Sco.4qmH1OGfUUmOcuRmfae0dPJhjX1Bq0yYhqbNi

例3 password_hash() で、適切なコストを探す例

このコードは、サーバーをベンチマークして、 ユーザー体験を悪化させることなく、 どの程度のコストに耐えられるかを判断します。 サーバーに負荷をかけすぎない範囲で、 できるだけ高めのコストを設定することをお勧めします。 基準として 11 程度からはじめ、サーバーが十分に高速なら、 できるだけ上げていきましょう。 以下のコードでは、 ストレッチングの時間を 350 ミリ秒以内にすることを狙っています。 対話形式のログインを扱う際の許容時間としては、このあたりが適切でしょう。

    <?php
    $timeTarget = 0.350; // 350 ミリ秒

    $cost = 11;
    do {
        $cost++;
        $start = microtime(true);
        password_hash("test", PASSWORD_BCRYPT, ["cost" => $cost]);
        $end = microtime(true);
    } while (($end - $start) < $timeTarget);

    echo "Appropriate Cost Found: " . $cost - 1;
    ?>

上の例の出力は、 たとえば以下のようになります。

    Appropriate Cost Found: 13

例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 ミリ秒くらいに収まるくらいが適切です。 先ほどの例のスクリプトは、自分のハードウェア上での適切な bcrypt のコストを判断するための助けとなるでしょう。

> 注意: この関数がサポートするアルゴリズムの更新 (あるいはデフォルトのアルゴリズムの変更) は、必ず次の手順にのっとって行われます。

> - 新しく追加されたアルゴリズムがデフォルトになるまでには、 少なくとも一度は 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_needs_rehash

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_needs_rehash — 指定したハッシュがオプションにマッチするかどうかを調べる

### 説明

function 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$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.';

    $algorithm = PASSWORD_BCRYPT;
    // bcrypt の cost パラメータは、ハードウェアの性能の向上にあわせて変えることができます
    $options = ['cost' => 13];

    // 格納されたハッシュを、平文のパスワードに対して検証します
    if (password_verify($password, $hash)) {
        // ハッシュアルゴリズムやオプションが変更されたかを確認します。
        if (password_needs_rehash($hash, $algorithm, $options)) {
            // 変更された場合は新しいハッシュを計算して、古いものを置き換えます
            $newHash = password_hash($password, $algorithm, $options);

            // ユーザーのレコードを $newHash で更新します
        }

        // ログイン
    }
    ?>

# password_verify

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

password_verify — パスワードがハッシュにマッチするかどうかを調べる

### 説明

function 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$12$4Umg0rCJwMswRw/l.SwHvuQV01coP0eWmGzd61QH2RvAOMANUBGC.';

    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() - パスワードが、ハッシュ値と一致するかを調べる

## 目次

- password_algos — 利用可能なパスワードハッシュアルゴリズムのIDを取得する
- password_get_info — 指定したハッシュに関する情報を返す
- password_hash — パスワードハッシュを作る
- password_needs_rehash — 指定したハッシュがオプションにマッチするかどうかを調べる
- password_verify — パスワードがハッシュにマッチするかどうかを調べる

- インストール/設定
  - 要件
  - インストール手順
- 定義済み定数
- Password Hashing 関数
  - password_algos — 利用可能なパスワードハッシュアルゴリズムのIDを取得する
  - password_get_info — 指定したハッシュに関する情報を返す
  - password_hash — パスワードハッシュを作る
  - password_needs_rehash — 指定したハッシュがオプションにマッチするかどうかを調べる
  - password_verify — パスワードがハッシュにマッチするかどうかを調べる

# Rnp

# はじめに

警告

この拡張モジュールは、 実験的 なものです。この拡張モジュールの動作・ 関数名・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 このモジュールは自己責任で使用してください。

This module allows you to use » RNP library. RNP is a high performance C++ OpenPGP library used by Mozilla Thunderbird.

# インストール/設定

## 目次

- 要件
- インストール手順

## 要件

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

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

(PECL rnp >= 0.1.1)

rnp_backend_string — Return cryptographic backend library name

### 説明

function rnp_backend_string(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Backend name string. Currently supported backends are "Botan" and "OpenSSL".

# rnp_backend_version

(PECL rnp >= 0.1.1)

rnp_backend_version — Return cryptographic backend library version

### 説明

function rnp_backend_version(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Version string.

# rnp_decrypt

(PECL rnp >= 0.1.1)

rnp_decrypt — Decrypt PGP message

### 説明

function 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` を返します.

# rnp_dump_packets

(PECL rnp >= 0.1.1)

rnp_dump_packets — Dump OpenPGP packets stream information in humand-readable format

### 説明

function 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` を返します.

# rnp_dump_packets_to_json

(PECL rnp >= 0.1.1)

rnp_dump_packets_to_json — Dump OpenPGP packets stream information to the JSON string

### 説明

function 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` を返します.

# rnp_ffi_create

(PECL rnp >= 0.1.1)

rnp_ffi_create — Create the top-level object used for interacting with the library

### 説明

function 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` を返します.

# rnp_ffi_destroy

(PECL rnp >= 0.1.1)

rnp_ffi_destroy — Destroy the top-level object used for interacting with the library

### 説明

function rnp_ffi_destroy(RnpFFI `$ffi`): void

### パラメータ

`ffi`
  The FFI object returned by rnp_ffi_create().

### 戻り値

# rnp_ffi_set_pass_provider

(PECL rnp >= 0.1.1)

rnp_ffi_set_pass_provider — Set password provider callback function

### 説明

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:

  function 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');

# 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

### 説明

function 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` を返します.

# rnp_import_signatures

(PECL rnp >= 0.1.1)

rnp_import_signatures — Import standalone signatures to the keyring and receive JSON describing updated keys

### 説明

function 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` を返します.

# rnp_key_export

(PECL rnp >= 0.1.1)

rnp_key_export — Export a key

### 説明

function 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` を返します.

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

### 説明

function 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` を返します.

# rnp_key_export_revocation

(PECL rnp >= 0.1.1)

rnp_key_export_revocation — Generate and export primary key revocation signature

### 説明

function 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` を返します.

# rnp_key_get_info

(PECL rnp >= 0.1.1)

rnp_key_get_info — Get information about the key

### 説明

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

# rnp_key_remove

(PECL rnp >= 0.1.1)

rnp_key_remove — Remove a key from keyring(s)

### 説明

function 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` を返します.

# rnp_key_revoke

(PECL rnp >= 0.1.1)

rnp_key_revoke — Revoke a key or subkey by generating and adding revocation signature

### 説明

function 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` を返します.

# rnp_list_keys

(PECL rnp >= 0.1.1)

rnp_list_keys — Enumerate all keys present in a keyring by specified identifer type

### 説明

function 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` を返します.

# rnp_load_keys

(PECL rnp >= 0.1.1)

rnp_load_keys — Load keys from PHP string

### 説明

function 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` を返します.

# rnp_load_keys_from_path

(PECL rnp >= 0.1.1)

rnp_load_keys_from_path — Load keys from specified path

### 説明

function 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` を返します.

# rnp_locate_key

(PECL rnp >= 0.1.1)

rnp_locate_key — Search for the key

### 説明

function 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` を返します.

# rnp_op_encrypt

(PECL rnp >= 0.1.1)

rnp_op_encrypt — Encrypt message

### 説明

function 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` を返します.

# rnp_op_generate_key

(PECL rnp >= 0.1.1)

rnp_op_generate_key — Generate key

### 説明

function 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().

# rnp_op_sign

(PECL rnp >= 0.1.1)

rnp_op_sign — Perform signing operation on a binary data, return embedded signature(s)

### 説明

function 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` を返します.

# rnp_op_sign_cleartext

(PECL rnp >= 0.1.1)

rnp_op_sign_cleartext — Perform signing operation on a textual data, return cleartext signed message

### 説明

function 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` を返します.

# rnp_op_sign_detached

(PECL rnp >= 0.1.1)

rnp_op_sign_detached — Perform signing operation, return detached signature(s)

### 説明

function 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` を返します.

# rnp_op_verify

(PECL rnp >= 0.1.1)

rnp_op_verify — Verify embedded or cleartext signatures

### 説明

function 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'.

# rnp_op_verify_detached

(PECL rnp >= 0.1.1)

rnp_op_verify_detached — Verify detached signatures

### 説明

function 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'.

# rnp_save_keys

(PECL rnp >= 0.1.1)

rnp_save_keys — Save keys to PHP string

### 説明

function 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` を返します.

# rnp_save_keys_to_path

(PECL rnp >= 0.1.1)

rnp_save_keys_to_path — Save keys to specified path

### 説明

function 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` を返します.

# rnp_supported_features

(PECL rnp >= 0.1.1)

rnp_supported_features — Get supported features in JSON format

### 説明

function 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_version_string

(PECL rnp >= 0.1.1)

rnp_version_string — RNP library version

### 説明

function rnp_version_string(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns RNP library version string.

# rnp_version_string_full

(PECL rnp >= 0.1.1)

rnp_version_string_full — Full version string of RNP library

### 説明

function rnp_version_string_full(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns full version string of RNP library.

## 目次

- 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

# The RnpFFI class

(PECL rnp >= 0.1.1)

## はじめに

## クラス概要

class RnpFFI {
}

- インストール/設定
  - 要件
  - インストール手順
- 定義済み定数
- 例
  - 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

# Sodium

# はじめに

Sodium は、 暗号化、復号化、署名、パスワードのハッシュ化その他の用途に使える、 モダンで使いやすいソフトウェアライブラリです。 より高レベルな暗号化ツールを作るための、 コアな操作を全て提供することを目標としています。

# インストール/設定

## 目次

- 要件
- インストール手順

## 要件

この拡張モジュールには、» 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_AEGIS128L_KEYBYTES` (int)
  PHP 8.4.0 以降で利用可能です。
`SODIUM_CRYPTO_AEAD_AEGIS128L_NSECBYTES` (int)
  PHP 8.4.0 以降で利用可能です。
`SODIUM_CRYPTO_AEAD_AEGIS128L_NPUBBYTES` (int)
  PHP 8.4.0 以降で利用可能です。
`SODIUM_CRYPTO_AEAD_AEGIS128L_ABYTES` (int)
  PHP 8.4.0 以降で利用可能です。
`SODIUM_CRYPTO_AEAD_AEGIS256_KEYBYTES` (int)
  PHP 8.4.0 以降で利用可能です。
`SODIUM_CRYPTO_AEAD_AEGIS256_NSECBYTES` (int)
  PHP 8.4.0 以降で利用可能です。
`SODIUM_CRYPTO_AEAD_AEGIS256_NPUBBYTES` (int)
  PHP 8.4.0 以降で利用可能です。
`SODIUM_CRYPTO_AEAD_AEGIS256_ABYTES` (int)
  PHP 8.4.0 以降で利用可能です。
`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

(PHP 7 >= 7.2.0, PHP 8)

sodium_add — 巨大な数を加算する

### 説明

function sodium_add(string `&$string1`, string `$string2`): void

この関数は、 引数 `string2` を `string1` に加算し、 `string1` の値を上書きします。 この関数は、両方の引数が、 符号なし整数をリトルエンディアンで表現した バイナリ文字列であると想定しています。

### パラメータ

`string1`
  符号なし整数をリトルエンディアンで表現した 任意の長さの文字列。 この引数はリファレンス渡しされ、 ふたつの引数の和を保持します。
`string2`
  符号なし整数をリトルエンディアンで表現した 任意の長さの文字列。

### 戻り値

値を返しません。

# sodium_base642bin

(PHP 7 >= 7.2.0, PHP 8)

sodium_base642bin — base64 エンコードされた文字列を、生バイナリにデコードする

### 説明

function 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. 空白文字)

### 戻り値

デコードされた文字列を返します。

# sodium_bin2base64

(PHP 7 >= 7.2.0, PHP 8)

sodium_bin2base64 — 生バイナリを base64 文字列にエンコードする

### 説明

function 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 エンコードされた文字列を返します。

# sodium_bin2hex

(PHP 7 >= 7.2.0, PHP 8)

sodium_bin2hex — 16進数にエンコードする

### 説明

function sodium_bin2hex(#[\SensitiveParameter] string `$string`): string

生バイナリ文字列を16進文字列にエンコードします。 標準の16進文字列にエンコードする関数と異なり、 sodium_bin2hex() は定数時間 (この性質は、プレーンテキストや鍵のような、 暗号に関する入力に触れるあらゆるコードで重要です) で実行できます。

### パラメータ

`string`
  生のバイナリ文字列。

### 戻り値

16進数にエンコードされた文字列を返します。

# sodium_compare

(PHP 7 >= 7.2.0, PHP 8)

sodium_compare — 巨大な数を比較する

### 説明

function sodium_compare(#[\SensitiveParameter] string `$string1`, #[\SensitiveParameter] string `$string2`): int

任意の長さの、 符号なし整数をリトルエンディアンで表現したバイナリ文字列として、 ふたつの文字列を比較します。 サイドチャネル攻撃によるリークはありません。

### パラメータ

`string1`
  左オペランド
`string2`
  右オペランド

### 戻り値

`string1` が `string2` より小さい場合は `-1` を返します。

`string1` が `string2` より大きい場合は `1` を返します。

ふたつの文字列が等しい場合 `0` を返します。

# sodium_crypto_aead_aegis128l_decrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis128l_decrypt — AEGIS-128L を用いてメッセージを検証し、復号する

### 説明

function sodium_crypto_aead_aegis128l_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter] string `$key`
): string|false

AEGIS-128L を用いてメッセージを検証し、復号します。

### パラメータ

`ciphertext`
  sodium_crypto_aead_aegis128l_encrypt() が生成したフォーマットでなければなりません。
`additional_data`
  追加の認証データ。 これは、 暗号化されたテキストに追加された認証タグを検証するのに用いられますが、 このデータは暗号化されていませんし、 暗号化されたテキストにも保存されていません。
`nonce`
  メッセージごとに一度だけ使われる数値。
`key`
  暗号化キー(128ビット).

### 戻り値

成功時にプレーンテキストを返します。 失敗した場合に `false` を返します

### 参考

- sodium_crypto_aead_aegis128l_encrypt() - AEGIS-128L を使って暗号化し、認証を行う
- sodium_crypto_aead_aegis128l_keygen() - ランダムな AEGIS-128L 暗号化キーを生成する

# sodium_crypto_aead_aegis128l_encrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis128l_encrypt — AEGIS-128L を使って暗号化し、認証を行う

### 説明

function sodium_crypto_aead_aegis128l_encrypt(
#[\SensitiveParameter] string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter] string `$key`
): string

AEGIS-128L を使って暗号化し、認証を行います。

### パラメータ

`message`
  暗号化するプレーンテキスト
`additional_data`
  追加の認証データ。 これは、 暗号化されたテキストに追加された認証タグを検証するのに用いられますが、 このデータは暗号化されていませんし、 暗号化されたテキストにも保存されません。
`nonce`
  メッセージごとに一度だけ使われる数値。
`key`
  暗号化キー(128ビット).

### 戻り値

暗号化されたテキストと、 認証タグを生のバイナリのバイト列に含めた文字列を返します。

### 参考

- sodium_crypto_aead_aegis128l_decrypt() - AEGIS-128L を用いてメッセージを検証し、復号する
- sodium_crypto_aead_aegis128l_keygen() - ランダムな AEGIS-128L 暗号化キーを生成する

# sodium_crypto_aead_aegis128l_keygen

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis128l_keygen — ランダムな AEGIS-128L 暗号化キーを生成する

### 説明

function sodium_crypto_aead_aegis128l_keygen(): string

sodium_crypto_aead_aegis128l_encrypt() や sodium_crypto_aead_aegis128l_decrypt() で使うランダムな鍵を生成します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

128ビット長のランダムな暗号化キーを返します。

### 参考

- sodium_crypto_aead_aegis128l_decrypt() - AEGIS-128L を用いてメッセージを検証し、復号する
- sodium_crypto_aead_aegis128l_encrypt() - AEGIS-128L を使って暗号化し、認証を行う

# sodium_crypto_aead_aegis256_decrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis256_decrypt — AEGIS-256 を用いてメッセージを検証し、復号する

### 説明

function sodium_crypto_aead_aegis256_decrypt(
string `$ciphertext`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter] string `$key`
): string|false

AEGIS-256 を用いてメッセージを検証し、復号します。

### パラメータ

`ciphertext`
  sodium_crypto_aead_aegis256_encrypt() が生成したフォーマットでなければなりません。
`additional_data`
  追加の認証データ。 これは、 暗号化されたテキストに追加された認証タグを検証するのに用いられますが、 このデータは暗号化されていませんし、 暗号化されたテキストにも保存されていません。
`nonce`
  メッセージごとに一度だけ使われる数値。
`key`
  暗号化キー(256ビット)

### 戻り値

成功時にプレーンテキストを返します。 失敗した場合に `false` を返します.

### 参考

- sodium_crypto_aead_aegis256_encrypt() - AEGIS-256 を使って暗号化し、認証を行う
- sodium_crypto_aead_aegis256_keygen() - ランダムな AEGIS-256 暗号化キーを生成する

# sodium_crypto_aead_aegis256_encrypt

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis256_encrypt — AEGIS-256 を使って暗号化し、認証を行う

### 説明

function sodium_crypto_aead_aegis256_encrypt(
#[\SensitiveParameter] string `$message`,
string `$additional_data`,
string `$nonce`,
#[\SensitiveParameter] string `$key`
): string

AEGIS-256 を使って暗号化し、認証を行います。

### パラメータ

`message`
  暗号化するプレーンテキスト
`additional_data`
  追加の認証データ。 これは、 暗号化されたテキストに追加された認証タグを検証するのに用いられますが、 このデータは暗号化されていませんし、 暗号化されたテキストにも保存されません。
`nonce`
  メッセージごとに一度だけ使われる数値。
`key`
  暗号化キー(256ビット)

### 戻り値

暗号化されたテキストと、 認証タグを生のバイナリのバイト列に含めた文字列を返します。

### 参考

- sodium_crypto_aead_aegis256_decrypt() - AEGIS-256 を用いてメッセージを検証し、復号する
- sodium_crypto_aead_aegis256_keygen() - ランダムな AEGIS-256 暗号化キーを生成する

# sodium_crypto_aead_aegis256_keygen

(PHP 8 >= 8.4.0)

sodium_crypto_aead_aegis256_keygen — ランダムな AEGIS-256 暗号化キーを生成する

### 説明

function sodium_crypto_aead_aegis256_keygen(): string

sodium_crypto_aead_aegis256_encrypt() や sodium_crypto_aead_aegis256_decrypt() で使うランダムな鍵を生成します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

256ビット長のランダムな暗号化キーを返します。

### 参考

- sodium_crypto_aead_aegis256_decrypt() - AEGIS-256 を用いてメッセージを検証し、復号する
- sodium_crypto_aead_aegis256_encrypt() - AEGIS-256 を使って暗号化し、認証を行う

# sodium_crypto_aead_aes256gcm_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_decrypt — AES-256-GCM を用いてメッセージを検証し、復号する

### 説明

function 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` を返します

# sodium_crypto_aead_aes256gcm_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_encrypt — AES-256-GCM を使って暗号化し、認証を行う

### 説明

function 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ビット)

### 戻り値

暗号化されたテキストと、 認証タグを生のバイナリのバイト列に含めた文字列を返します。 (フォーマット: 暗号化済みテキストの後に、タグが続きます)

# sodium_crypto_aead_aes256gcm_is_available

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_is_available — ハードウェアが AES256-GCM をサポートしているかを確認する

### 説明

function sodium_crypto_aead_aes256gcm_is_available(): bool

この関数の戻り値は、 ハードウェアが AES256-GCM をサポートしているかどうかに依存します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

AES-256-GCM を使って暗号化しても安全な場合、`true` を返します。 そうでない場合、`false` を返します。

# sodium_crypto_aead_aes256gcm_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_aes256gcm_keygen — ランダムな AES-256-GCM 暗号化キーを生成する

### 説明

function sodium_crypto_aead_aes256gcm_keygen(): string

sodium_crypto_aead_aes256gcm_encrypt() や sodium_crypto_aead_aes256gcm_decrypt() で使うランダムな鍵を生成します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

256ビット長のランダムな暗号化キーを返します。

# sodium_crypto_aead_chacha20poly1305_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_decrypt — ChaCha20-Poly1305 を用いてメッセージを検証し、復号する

### 説明

function 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` を返します

# sodium_crypto_aead_chacha20poly1305_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_encrypt — ChaCha20-Poly1305 を使って暗号化し、認証を行う

### 説明

function 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_ietf_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_decrypt — 暗号化されたテキストが、有効なタグを持っているかを調べる

### 説明

function 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_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_encrypt — メッセージを暗号化する

### 説明

function 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` を返します.

# sodium_crypto_aead_chacha20poly1305_ietf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_ietf_keygen — ランダムな ChaCha20-Poly1305 (IETF) 暗号化キーを生成する

### 説明

function sodium_crypto_aead_chacha20poly1305_ietf_keygen(): string

sodium_crypto_aead_chacha20poly1305_ietf_encrypt() や sodium_crypto_aead_chacha20poly1305_ietf_decrypt() で使うランダムな鍵を生成します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

256ビット長のランダムな暗号化キーを返します。

# sodium_crypto_aead_chacha20poly1305_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_chacha20poly1305_keygen — ランダムな ChaCha20-Poly1305 暗号化キーを生成する

### 説明

function sodium_crypto_aead_chacha20poly1305_keygen(): string

sodium_crypto_aead_chacha20poly1305_encrypt() や sodium_crypto_aead_chacha20poly1305_decrypt() で使うランダムな鍵を生成します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

256ビット長のランダムな暗号化キーを返します。

# sodium_crypto_aead_xchacha20poly1305_ietf_decrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_decrypt — XChaCha20-Poly1305 を用いてメッセージを検証し、復号する(AEADモードのうちもっとも好ましい)

### 説明

function 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_xchacha20poly1305_ietf_encrypt() が生成したフォーマット (暗号化されたテキスト、タグを連結したもの) でなければなりません。
`additional_data`
  追加の認証データ。 これは、 暗号化されたテキストに追加された認証タグを検証するのに用いられますが、 このデータは暗号化されていませんし、 暗号化されたテキストにも保存されていません。
`nonce`
  メッセージごとに一度だけ使われる数値。 長さは24バイトです。 これは、 (たとえば、random_bytes()を使って) ランダムな値を生成するのに十分大きな長さです。
`key`
  暗号化キー(256ビット)

### 戻り値

成功時にプレーンテキストを返します。 失敗した場合に `false` を返します

# sodium_crypto_aead_xchacha20poly1305_ietf_encrypt

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_encrypt — XChaCha20-Poly1305 を使って暗号化し、認証を行う(AEADモードのうちもっとも好ましい)

### 説明

function 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` を返します.

# sodium_crypto_aead_xchacha20poly1305_ietf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_aead_xchacha20poly1305_ietf_keygen — ランダムな XChaCha20-Poly1305 暗号化キーを生成する

### 説明

function sodium_crypto_aead_xchacha20poly1305_ietf_keygen(): string

sodium_crypto_aead_xchacha20poly1305_ietf_encrypt() や sodium_crypto_aead_xchacha20poly1305_ietf_decrypt() で使うランダムな鍵を生成します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

256ビット長のランダムな暗号化キーを返します。

# sodium_crypto_auth

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth — メッセージに対応するタグを計算する

### 説明

function sodium_crypto_auth(string `$message`, #[\SensitiveParameter] string `$key`): string

対称鍵によるメッセージ認証を行います。 sodium_crypto_auth() は完全性は提供しますが、機密性は提供しません。

(sodium_crypto_sign_detached() のような) 電子署名と異なり、 メッセージを検証する側は、 自分たちのメッセージを認証することもできます。 (つまり、対称鍵による認証です)

### パラメータ

`message`
  認証したいメッセージ
`key`
  認証鍵

### 戻り値

認証タグを返します。

# sodium_crypto_auth_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth_keygen — sodium_crypto_auth で使う、ランダムな鍵を生成する

### 説明

function sodium_crypto_auth_keygen(): string

sodium_crypto_auth() や sodium_crypto_auth_verify() で使う鍵を生成します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

256ビット長のランダムな暗号化キーを返します。

# sodium_crypto_auth_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_auth_verify — メッセージのタグが有効かどうかを検証する

### 説明

function 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_box

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box — 認証付きの公開鍵による暗号化

### 説明

function 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_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_keypair — 秘密鍵と、それに対応する公開鍵をランダムに生成する

### 説明

function sodium_crypto_box_keypair(): string

秘密鍵と公開鍵を、ひとつの文字列として生成します。

この関数で生成する鍵ペアの文字列から秘密鍵を取り出すには、 sodium_crypto_box_secretkey() を参照ください。 この関数で生成する鍵ペアの文字列から公開鍵を取り出すには、 sodium_crypto_box_publickey() を参照ください。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

X25519 形式の秘密鍵と、 それに対応する公開鍵を両方含んだ文字列を返します。

# sodium_crypto_box_keypair_from_secretkey_and_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_keypair_from_secretkey_and_publickey — 秘密鍵と公開鍵から、鍵ペアを生成する

### 説明

function 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_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_open — 認証付きの公開鍵による復号

### 説明

function 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` を返します.

# sodium_crypto_box_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_publickey — crypto_box 鍵ペアから、公開鍵を取り出す

### 説明

function 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_from_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_publickey_from_secretkey — 秘密鍵から公開鍵を計算する

### 説明

function 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 with the corresponding parameters; 略して Ed25519) では動作しません。

### パラメータ

`secret_key`
  X25519 形式の秘密鍵

### 戻り値

X25519 形式の公開鍵を返します。

# sodium_crypto_box_seal

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seal — 匿名の公開鍵暗号による暗号化

### 説明

function 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_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seal_open — 匿名の公開鍵暗号による復号

### 説明

function 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!"

# sodium_crypto_box_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_secretkey — crypto_box 鍵ペアから、秘密鍵を取り出す

### 説明

function sodium_crypto_box_secretkey(#[\SensitiveParameter] string `$key_pair`): string

鍵ペアを指定し、秘密鍵だけを取り出します。

### パラメータ

`key_pair`
  sodium_crypto_box_keypair() や sodium_crypto_box_seed_keypair() によって生成された鍵ペア

### 戻り値

X25519 形式の秘密鍵を返します。

# sodium_crypto_box_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_box_seed_keypair — 単一の鍵から、結果がひとつに定まる鍵ペアを派生させる

### 説明

function sodium_crypto_box_seed_keypair(#[\SensitiveParameter] string `$seed`): string

秘密鍵を生成するためのシードを介して、 公開鍵を派生させ、秘密鍵と公開鍵のふたつを鍵ペアとして返します。

`*_seed_keypair` 関数はパスワードとソルトから鍵ペアを生成することと同じです。 `seed` としての結果を、 鍵を生成するために使います。

### パラメータ

`seed`
  暗号の処理をした入力。 長さは32バイトでなければなりません。

### 戻り値

X25519 形式のキーペア(秘密鍵と公開鍵)を返します。

# sodium_crypto_core_ristretto255_add

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_add — 要素を追加する

### 説明

function 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_from_hash

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_from_hash — ベクトルをマップする

### 説明

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

# sodium_crypto_core_ristretto255_is_valid_point

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_is_valid_point — 座標が ristretto255 曲線上にあるかを調べる

### 説明

function 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_random

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_random — ランダムな鍵を生成する

### 説明

function 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_scalar_add

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_add — スカラー値を追加する

### 説明

function 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() - スカラー値を減らす

# 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

### 説明

function 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_invert

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_invert — スカラー値を反転させる

### 説明

function 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_mul

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_mul — スカラー値を乗算する

### 説明

function 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_negate

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_negate — スカラー値の論理否定を行う

### 説明

function 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_random

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_random — ランダムな鍵を生成する

### 説明

function 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_reduce

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_reduce — スカラー値を縮小する

### 説明

function 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_sub

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_scalar_sub — スカラー値を減らす

### 説明

function 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_sub

(PHP 8 >= 8.1.0)

sodium_crypto_core_ristretto255_sub — 要素の値を減らす

### 説明

function 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_generichash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash — メッセージのハッシュ値を得る

### 説明

function 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_final

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_final — ハッシュ値を計算する

### 説明

function 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_init

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_init — ストリーミングのためにハッシュを初期化する

### 説明

function 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_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_keygen — ランダムなハッシュキーを生成する

### 説明

function sodium_crypto_generichash_keygen(): string

ハッシュAPIで使うランダムなキーを生成します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

ランダムな 256ビット長のキーを返します。

# sodium_crypto_generichash_update

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_generichash_update — メッセージをハッシュに追加する

### 説明

function 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_kdf_derive_from_key

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kdf_derive_from_key — サブキーを派生させる

### 説明

function 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`
  サブキーを派生させるルートキー

### 戻り値

擬似ランダムな(生のバイナリの)バイト列を文字列として返します。

# sodium_crypto_kdf_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kdf_keygen — KDF インターフェイスのために、ランダムなルートキーを生成する

### 説明

function sodium_crypto_kdf_keygen(): string

sodium_crypto_kdf_derive_from_key() で使うルートキーに適合する、ランダムなキーを生成します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

ランダムな256ビット長のキーを返します。

# sodium_crypto_kx_client_session_keys

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_client_session_keys — クライアント側のセッションキーを計算する

### 説明

function 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_crypto_kx_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_keypair — 新しい sodium の鍵ペアを生成する

### 説明

function 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

# sodium_crypto_kx_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_publickey — crypto_kx 鍵ペアから、公開鍵を取り出す

### 説明

function sodium_crypto_kx_publickey(#[\SensitiveParameter] string `$key_pair`): string

crypto_kx の鍵ペアから、公開鍵を取り出します。

### パラメータ

`key_pair`
  X25519 形式の鍵ペア。 たとえば、sodium_crypto_kx_keypair() から生成されたものです。

### 戻り値

X25519 形式の公開鍵を返します。

# sodium_crypto_kx_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_secretkey — crypto_kx 鍵ペアから、秘密鍵を取り出す

### 説明

function sodium_crypto_kx_secretkey(#[\SensitiveParameter] string `$key_pair`): string

crypto_kx 鍵ペアから、秘密鍵を取り出します。

### パラメータ

`key_pair`
  X25519 形式の鍵ペア。 たとえば、 sodium_crypto_kx_keypair() から生成されたものです。

### 戻り値

X25519 形式の秘密鍵を返します。

# sodium_crypto_kx_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_seed_keypair — Description

### 説明

function sodium_crypto_kx_seed_keypair(#[\SensitiveParameter] string `$seed`): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`seed`

### 戻り値

# sodium_crypto_kx_server_session_keys

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_kx_server_session_keys — サーバー側のセッションキーを計算する

### 説明

function 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 の公開鍵

### 戻り値

ふたつの文字列からなる配列を返します。 ひとつめはクライアントから受信する文字列として使います。 ふたつめはクライアントに送信するデータとして使います。

# sodium_crypto_pwhash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash — Argon2 アルゴリズムを使い、パスワードからキーを導出する

### 説明

function 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

# sodium_crypto_pwhash_scryptsalsa208sha256

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256 — scrypt を使い、パスワードからキーを導出する

### 説明

function 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` と一致するものとペアになるべきです。

### 戻り値

指定された長さのバイト列を文字列として返します。

# sodium_crypto_pwhash_scryptsalsa208sha256_str

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256_str — ASCII 文字列でエンコードされたハッシュを得る

### 説明

function sodium_crypto_pwhash_scryptsalsa208sha256_str(#[\SensitiveParameter] string `$password`, int `$opslimit`, int `$memlimit`): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`password`
`opslimit`
`memlimit`

### 戻り値

# sodium_crypto_pwhash_scryptsalsa208sha256_str_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_scryptsalsa208sha256_str_verify — パスワードが、有効なパスワード検証文字列かを調べる

### 説明

function sodium_crypto_pwhash_scryptsalsa208sha256_str_verify(string `$hash`, #[\SensitiveParameter] string `$password`): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`hash`
`password`

### 戻り値

# sodium_crypto_pwhash_str

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str — ASCII 文字でエンコードされたハッシュ値を得る

### 説明

function 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_needs_rehash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str_needs_rehash — パスワードを再計算する必要があるかを判定する

### 説明

function 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_verify

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_pwhash_str_verify — パスワードが、ハッシュ値と一致するかを調べる

### 説明

function 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_scalarmult

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_scalarmult — ユーザーの秘密鍵と、別のユーザーの公開鍵を使って、共有シークレットを計算する

### 説明

function sodium_crypto_scalarmult(string `$n`, string `$p`): string

ディフィー・ヘルマン楕円曲線上で座標pをn回掛け算します。

### パラメータ

`n`
  スカラー値。 これは通常は秘密鍵です。
`p`
  座標 (X軸上)。 これは通常は公開鍵です。

### 戻り値

32バイト長のランダムな文字列を返します。

# 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_ristretto255

(PHP 8 >= 8.1.1)

sodium_crypto_scalarmult_ristretto255 — 共有シークレットを計算する

### 説明

function 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_base

(PHP 8 >= 8.1.1)

sodium_crypto_scalarmult_ristretto255_base — 秘密鍵から公開鍵を計算する

### 説明

function sodium_crypto_scalarmult_ristretto255_base(string `$n`): string

秘密鍵を指定すると、それに対応する公開鍵を計算します。 libsodium 1.0.18 以降で利用可能です。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`n`
  秘密鍵。

### 戻り値

32バイト長のランダムな文字列を返します。

### 参考

- sodium_crypto_scalarmult_ristretto255() - 共有シークレットを計算する

# sodium_crypto_secretbox

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretbox — 認証付きの共有鍵による暗号化

### 説明

function 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_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretbox_keygen — sodium_crypto_secretbox で使うランダムな鍵を生成する

### 説明

function 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_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretbox_open — 認証付きの共有鍵による復号

### 説明

function 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_secretstream_xchacha20poly1305_init_pull

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_init_pull — 復号のためのシークレットストリームのコンテキストを初期化する

### 説明

function 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_push

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_init_push — 暗号化のために、シークレットストリームのコンテキストを初期化する

### 説明

function 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_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_keygen — ランダムなシークレットストリームのキーを生成する

### 説明

function sodium_crypto_secretstream_xchacha20poly1305_keygen(): string

ランダムなシークレットストリームのキーを生成します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

ランダムなバイト列からなる文字列を返します。

# sodium_crypto_secretstream_xchacha20poly1305_pull

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_pull — 暗号化されたストリームから、データのチャンクを複号する

### 説明

function 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`: このメッセージを暗号化するために、 これまでに使われてきた鍵を"忘れ"ます。 そして、新しい秘密鍵を生成します。

# sodium_crypto_secretstream_xchacha20poly1305_push

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_push — ストリーミングAPI で安全に復号できるように、データのチャンクを暗号化する

### 説明

function 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_rekey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_secretstream_xchacha20poly1305_rekey — シークレットストリームのステート中で、鍵を入れ替える

### 説明

function sodium_crypto_secretstream_xchacha20poly1305_rekey(string `&$state`): void

シークレットストリームのステート中で、鍵を明示的に入れ替えます。 渡された値は上書きされます。

### パラメータ

`state`
  シークレットストリームのステート

### 戻り値

値を返しません。

# sodium_crypto_shorthash

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_shorthash — メッセージと鍵のための短いハッシュ値を計算する

### 説明

function 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_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_shorthash_keygen — 鍵のためのランダムなバイト値を得る

### 説明

function sodium_crypto_shorthash_keygen(): string

sodium_crypto_shorthash() で使うための鍵を生成します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# sodium_crypto_sign

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign — メッセージに署名する

### 説明

function sodium_crypto_sign(string `$message`, #[\SensitiveParameter] string `$secret_key`): string

秘密鍵を用いてメッセージに署名します。 これは、秘密鍵に対応する公開鍵で検証することができます。 この関数は、メッセージに署名を付加します。 メッセージとは別に署名を持つ方法については、 sodium_crypto_sign_detached() を参照ください。

### パラメータ

`message`
  署名するメッセージ
`secret_key`
  秘密鍵。 sodium_crypto_sign_secretkey() を参照ください。

### 戻り値

署名済みのメッセージ(暗号化されていません) を返します。

# sodium_crypto_sign_detached

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_detached — メッセージに署名する

### 説明

function sodium_crypto_sign_detached(string `$message`, #[\SensitiveParameter] string `$secret_key`): string

秘密鍵を使って署名します。 この署名は、対応する公開鍵で検証できます。 この関数は、メッセージとは別の署名を返します。

### パラメータ

`message`
  署名するメッセージ
`secret_key`
  秘密鍵。 sodium_crypto_sign_secretkey() を参照ください。

### 戻り値

署名を返します。

# sodium_crypto_sign_ed25519_pk_to_curve25519

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_ed25519_pk_to_curve25519 — Ed25519 公開鍵を、Curve25519 公開鍵に変換する

### 説明

function sodium_crypto_sign_ed25519_pk_to_curve25519(string `$public_key`): string

指定された Ed25519 形式の公開鍵から、 双有理同値な X25519 形式の公開鍵を計算します。

### パラメータ

`public_key`
  crypto_sign 関数に適合する公開鍵

### 戻り値

crypto_box 関数に適合する公開鍵を返します。

# sodium_crypto_sign_ed25519_sk_to_curve25519

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_ed25519_sk_to_curve25519 — Ed25519 秘密鍵を、Curve25519 秘密鍵に変換する

### 説明

function sodium_crypto_sign_ed25519_sk_to_curve25519(#[\SensitiveParameter] string `$secret_key`): string

指定された Ed25519 形式の秘密鍵から、 双有理同値な X25519 形式の秘密鍵を計算します。

### パラメータ

`secret_key`
  crypto_sign 関数に適合する秘密鍵

### 戻り値

crypto_box 関数に適合する秘密鍵を返します。

# sodium_crypto_sign_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_keypair — 秘密鍵と、対応する公開鍵をランダムに生成する

### 説明

function sodium_crypto_sign_keypair(): string

ランダムな Ed25519 形式の鍵ペアをひとつの文字列として生成します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Ed25519 形式の鍵ペアを返します。

# sodium_crypto_sign_keypair_from_secretkey_and_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_keypair_from_secretkey_and_publickey — 秘密鍵と公開鍵を結合する

### 説明

function 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_open

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_open — 署名済みのメッセージが、有効な署名を持っているかを調べる

### 説明

function sodium_crypto_sign_open(string `$signed_message`, string `$public_key`): string|false

メッセージに付加された署名を検証し、メッセージを返します。

### パラメータ

`signed_message`
  sodium_crypto_sign() を使って署名されたメッセージ
`public_key`
  Ed25519 形式の公開鍵

### 戻り値

成功時には、オリジナルの署名済みメッセージを返します。 失敗した場合に `false` を返します

# sodium_crypto_sign_publickey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_publickey — 鍵ペアから、Ed25519 形式の公開鍵を取り出す

### 説明

function sodium_crypto_sign_publickey(#[\SensitiveParameter] string `$key_pair`): string

鍵ペアから、Ed25519 形式の公開鍵を取り出します。

### パラメータ

`key_pair`
  Ed25519 形式の鍵ペア (sodium_crypto_sign_keypair() を参照ください)

### 戻り値

Ed25519 形式の公開鍵を返します。

# sodium_crypto_sign_publickey_from_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_publickey_from_secretkey — 秘密鍵から、Ed25519 形式の公開鍵を取り出す

### 説明

function sodium_crypto_sign_publickey_from_secretkey(#[\SensitiveParameter] string `$secret_key`): string

秘密鍵から、Ed25519 形式の公開鍵を取り出します。

### パラメータ

`secret_key`
  Ed25519 形式の秘密鍵

### 戻り値

Ed25519 形式の公開鍵を返します。

# sodium_crypto_sign_secretkey

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_secretkey — 鍵ペアから、Ed25519 形式の秘密鍵を取り出す

### 説明

function sodium_crypto_sign_secretkey(#[\SensitiveParameter] string `$key_pair`): string

鍵ペアから、Ed25519 形式の秘密鍵を取り出します。

### パラメータ

`key_pair`
  Ed25519 形式の鍵ペア (sodium_crypto_sign_keypair() を参照ください)

### 戻り値

Ed25519 形式の秘密鍵を返します。

# sodium_crypto_sign_seed_keypair

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_seed_keypair — 単一の鍵から、結果がひとつに定まる鍵ペアを派生させる

### 説明

function sodium_crypto_sign_seed_keypair(#[\SensitiveParameter] string `$seed`): string

秘密鍵を生成するためのシードを介して、 公開鍵を派生させ、秘密鍵と公開鍵のふたつを鍵ペアとして返します。

`*_seed_keypair` 関数はパスワードとソルトから鍵ペアを生成することと同じです。 `seed` としての結果を、 鍵を生成するために使います。

### パラメータ

`seed`
  暗号の処理をした入力。 長さは32バイトでなければなりません。

### 戻り値

鍵ペア(秘密鍵と公開鍵)を返します。

# sodium_crypto_sign_verify_detached

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_sign_verify_detached — メッセージの署名を検証する

### 説明

function 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_stream

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream — シードから、結果がひとつに定まるバイト列を生成する

### 説明

function sodium_crypto_stream(int `$length`, string `$nonce`, #[\SensitiveParameter] string `$key`): string

シードから、結果がひとつに定まるバイト列を生成します。 XSalsa20 ストリーム暗号を用います。

### パラメータ

`length`
  長さをバイト単位で指定します。
`nonce`
  メッセージごとに一度だけ使われる数値。 長さは24バイトです。 これは、 (たとえば、random_bytes()を使って) ランダムな値を生成するのに十分大きな長さです。
`key`
  暗号化キー(256ビット)

### 戻り値

擬似ランダムなバイト列を文字列として返します。

# sodium_crypto_stream_keygen

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream_keygen — sodium_crypto_stream で用いる、ランダムな鍵を生成する

### 説明

function sodium_crypto_stream_keygen(): string

sodium_crypto_stream() や sodium_crypto_stream_xor() で用いる鍵を生成します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

256ビット長の暗号化キーを返します。

# sodium_crypto_stream_xchacha20

(PHP 8 >= 8.1.0)

sodium_crypto_stream_xchacha20 — 秘密鍵と nonce を、疑似ランダムなバイト列の鍵ストリームに展開する

### 説明

function 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_keygen

(PHP 8 >= 8.1.0)

sodium_crypto_stream_xchacha20_keygen — ランダムな暗号化キーを生成する

### 説明

function sodium_crypto_stream_xchacha20_keygen(): string

sodium_crypto_stream_xchacha20() で使うランダムな鍵を生成して返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

sodium_crypto_stream_xchacha20() で使う、 32バイト長のランダムな暗号化キーを返します。

# sodium_crypto_stream_xchacha20_xor

(PHP 8 >= 8.1.0)

sodium_crypto_stream_xchacha20_xor — nonce と秘密鍵を使ってメッセージを暗号化する(認証なし)

### 説明

function 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 と秘密鍵を使ってメッセージを暗号化する(認証なし)

# sodium_crypto_stream_xchacha20_xor_ic

(PHP 8 >= 8.2.0)

sodium_crypto_stream_xchacha20_xor_ic — nonce と秘密鍵を使ってメッセージを暗号化する(認証なし)

### 説明

function 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_xor

(PHP 7 >= 7.2.0, PHP 8)

sodium_crypto_stream_xor — 認証を行わずにメッセージを暗号化する

### 説明

function sodium_crypto_stream_xor(#[\SensitiveParameter] string `$message`, string `$nonce`, #[\SensitiveParameter] string `$key`): string

この関数は XSalsa20 を用いて暗号化を行いますが、 プレーンテキストについて、 いかなる暗号学的な保証も行いません。

### パラメータ

`message`
  暗号化するメッセージ
`nonce`
  メッセージごとに一度だけ使われる数値。 長さは24バイトです。 これは、 (たとえば、random_bytes()を使って) ランダムな値を生成するのに十分大きな長さです。
`key`
  暗号化キー(256ビット)

### 戻り値

暗号化されたメッセージを返します。

# sodium_hex2bin

(PHP 7 >= 7.2.0, PHP 8)

sodium_hex2bin — 16進エンコードされたバイナリ文字列をデコードする

### 説明

function sodium_hex2bin(#[\SensitiveParameter] string `$string`, string `$ignore` = ""): string

16進エンコードされたバイナリ文字列をデコードします。

sodium_bin2hex() と同じく、 sodium_hex2bin() 関数はサイドチャネル攻撃に対する耐性がありますが、 hex2bin() はそうではありません。

### パラメータ

`string`
  データの16進表現。
`ignore`
  オプションで指定する、無視する文字

### 戻り値

指定された `string` のバイナリ表現を返します。

# sodium_increment

(PHP 7 >= 7.2.0, PHP 8)

sodium_increment — 巨大な数をインクリメントする

### 説明

function sodium_increment(string `&$string`): void

文字列をリトルエンディアンで表現した符号なし整数として扱い、 その値をインクリメントします。定数時間で動作します。

### パラメータ

`string`
  インクリメントする文字列。

### 戻り値

値を返しません。

# sodium_memcmp

(PHP 7 >= 7.2.0, PHP 8)

sodium_memcmp — 定数時間での文字列の比較

### 説明

function sodium_memcmp(#[\SensitiveParameter] string `$string1`, #[\SensitiveParameter] string `$string2`): int

ふたつの文字列を、定数時間で比較します。

実際、ほとんどの場合は hash_equals() を使いたいかもしれません。 なぜなら、同じロジックを提供しているにもかかわらず、 整数型ではなく、bool を返すからです。 しかしながら、タイミング攻撃に敏感な比較計算の結果を扱う場合、 かつ、bool値から整数型への変換の際の、 タイミングに依存した情報のリークを気にする場合、 sodium_memcmp() 関数が理想的な代替になります。

### パラメータ

`string1`
  比較対象の文字列
`string2`
  もう一つの、比較する文字列

### 戻り値

双方の文字列が等しければ `0` を返します。 等しくない場合 `-1` を返します。

# sodium_memzero

(PHP 7 >= 7.2.0, PHP 8)

sodium_memzero — 文字列をNUL文字で上書きする

### 説明

function sodium_memzero(#[\SensitiveParameter] string `&$string`): void

sodium_memzero() は、 リファレンス渡しされた文字列をゼロ埋めします。

### パラメータ

`string`
  文字列

### 戻り値

値を返しません。

# sodium_pad

(PHP 7 >= 7.2.0, PHP 8)

sodium_pad — パディングデータを追加する

### 説明

function sodium_pad(#[\SensitiveParameter] string `$string`, int `$block_size`): string

文字列の右側に、任意の長さのパディングを追加します。 タイミング攻撃に対しても安全です。

### パラメータ

`string`
  パディングされていない文字列。
`block_size`
  ここで指定されたブロックサイズの偶数倍になるまで、 文字列にパディングが追加されます。

### 戻り値

パディングが追加された文字列。

# sodium_unpad

(PHP 7 >= 7.2.0, PHP 8)

sodium_unpad — パディングを削除する

### 説明

function sodium_unpad(#[\SensitiveParameter] string `$string`, int `$block_size`): string

パディングされた文字列から、パディングを削除します。 タイミング攻撃に対しても安全です。

### パラメータ

`string`
  パディングされた文字列。
`block_size`
  パディングのブロックサイズ

### 戻り値

パディングが削除された文字列を返します。

## 目次

- sodium_add — 巨大な数を加算する
- sodium_base642bin — base64 エンコードされた文字列を、生バイナリにデコードする
- sodium_bin2base64 — 生バイナリを base64 文字列にエンコードする
- sodium_bin2hex — 16進数にエンコードする
- sodium_compare — 巨大な数を比較する
- sodium_crypto_aead_aegis128l_decrypt — AEGIS-128L を用いてメッセージを検証し、復号する
- sodium_crypto_aead_aegis128l_encrypt — AEGIS-128L を使って暗号化し、認証を行う
- sodium_crypto_aead_aegis128l_keygen — ランダムな AEGIS-128L 暗号化キーを生成する
- sodium_crypto_aead_aegis256_decrypt — AEGIS-256 を用いてメッセージを検証し、復号する
- sodium_crypto_aead_aegis256_encrypt — AEGIS-256 を使って暗号化し、認証を行う
- sodium_crypto_aead_aegis256_keygen — ランダムな AEGIS-256 暗号化キーを生成する
- 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 クラス

(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 function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

- インストール/設定
  - 要件
  - インストール手順
- 定義済み定数
- Sodium 関数
  - sodium_add — 巨大な数を加算する
  - sodium_base642bin — base64 エンコードされた文字列を、生バイナリにデコードする
  - sodium_bin2base64 — 生バイナリを base64 文字列にエンコードする
  - sodium_bin2hex — 16進数にエンコードする
  - sodium_compare — 巨大な数を比較する
  - sodium_crypto_aead_aegis128l_decrypt — AEGIS-128L を用いてメッセージを検証し、復号する
  - sodium_crypto_aead_aegis128l_encrypt — AEGIS-128L を使って暗号化し、認証を行う
  - sodium_crypto_aead_aegis128l_keygen — ランダムな AEGIS-128L 暗号化キーを生成する
  - sodium_crypto_aead_aegis256_decrypt — AEGIS-256 を用いてメッセージを検証し、復号する
  - sodium_crypto_aead_aegis256_encrypt — AEGIS-256 を使って暗号化し、認証を行う
  - sodium_crypto_aead_aegis256_keygen — ランダムな AEGIS-256 暗号化キーを生成する
  - 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 クラス

# Xpass

# はじめに

This extension provides password hashing algorithms used by Linux distributions, using extended crypt library.

It also provides additional functions from libxcrypt missing in core PHP.

# インストール/設定

## 目次

- 要件
- Installation via PECL

## 要件

This extension requires » libxcrypt version 4.4 or higher.

## Installation via PECL

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/xpass.

# 定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

Xpass extension provides various set of constants. Hash methods (`CRYPT_PREFIX_*`) for crypt_gensalt() prefix parameter. Error codes (`CRYPT_SALT_*`) returned by crypt_checksalt(). Password algorithms (`PASSWORD_*`) for password_hash() algo parameter.

Hashing methods
`CRYPT_PREFIX_STD_DES` (string)
  The original hashing method from Unix V7, based on the DES block cipher. Because DES is cheap on modern hardware, because there are only `4096` possible salts and 2**56 distinct passphrases, which it truncates to 8 characters, it is feasible to discover any passphrase hashed with this method. It should only be used when supporting old operating systems that support no other hash generation algorithm, due to how weak DES hashes are.
`CRYPT_PREFIX_EXT_DES` (string)
  An extension of traditional DES, which eliminates the length limit, increases the salt size, and makes the time cost tunable. It originates with BSDI BSD/OS and is also available on at least NetBSD, OpenBSD, and FreeBSD due to the use of David Burren's FreeSec library. It is much better than traditional DES and bigcrypt, but still should not be used for new hashes.
`CRYPT_PREFIX_MD5` (string)
  A hash based on the MD5 algorithm, originally developed by Poul-Henning Kamp for FreeBSD. Supported on most free Unixes and newer versions of Solaris. Not as weak as the DES-based hashes below, but MD5 is so cheap on modern hardware that it should not be used for new hashes. Processing cost is not adjustable.
`CRYPT_PREFIX_BLOWFISH` (string)
  A hash based on the Blowfish block cipher, modified to have an extra-expensive key schedule. Originally developed by Niels Provos and David Mazieres for OpenBSD and also supported on recent versions of FreeBSD and NetBSD, on Solaris 10 and newer, and on several GNU/*/Linux distributions.
`CRYPT_PREFIX_SHA256` (string)
  A hash based on SHA-2 with 256-bit output, originally developed by Ulrich Drepper for GNU libc. Supported on Linux but not common elsewhere. Acceptable for new hashes. The default processing cost parameter is `5000`, which is too low for modern hardware.
`CRYPT_PREFIX_SHA512` (string)
  A hash based on SHA-2 with 512-bit output, originally developed by Ulrich Drepper for GNU libc. Supported on Linux but not common elsewhere. Acceptable for new hashes. The default processing cost parameter is `5000`, which is too low for modern hardware.
`CRYPT_PREFIX_SCRYPT` (string)
  Scrypt is a password-based key derivation function created by Colin Percival, originally for the Tarsnap online backup service. The algorithm was specifically designed to make it costly to perform large-scale custom hardware attacks by requiring large amounts of memory. In 2016, the scrypt algorithm was published by IETF as RFC 7914.
`CRYPT_PREFIX_GOST_YESCRYPT` (string)
  Gost-yescrypt uses the output from yescrypt as an input message to HMAC with the GOST R 34.11-2012 (Streebog) hash function with a 256-bit digest. Thus, yescrypt's cryptographic properties are superseded by those of the GOST hash function. This hashing method is useful in applications that need modern passphrase hashing, but have to rely on GOST algorithms. The GOST R 34.11-2012 (Streebog) hash function has been published by the IETF as RFC 6986. Acceptable for new hashes where required.
`CRYPT_PREFIX_YESCRYPT` (string)
  Yescrypt is a scalable passphrase hashing scheme designed by Solar Designer, which is based on Colin Percival's scrypt. While yescrypt's strength against password guessing attacks comes from its algorithm design, its cryptographic security is guaranteed by its use of SHA-256 on the outer layer. The SHA-256 hash function has been published by NIST in FIPS PUB 180-2 (and its subsequent revisions such as FIPS PUB 180-4) and by the IETF as RFC 4634 (and subsequently RFC 6234). Recommended for new hashes.
`CRYPT_PREFIX_SM3CRYPT` (string)
  A hash based on the ShangMi 3 hash function with 256-bit output, that uses the same design as sha256crypt and/or sha512crypt. Supported on EulerOS, Kylin, openEuler, and openKylin, but not common elsewhere. Acceptable for new hashes where required. The default processing cost parameter is 5000, which is too low for modern hardware. Available as of 1.2.0 with libcxcrypt >= 4.5.0.
`CRYPT_PREFIX_SM3_YESCRYPT` (string)
  Sm3-yescrypt uses the output from yescrypt as an input message to HMAC with the ShangMi 3 hash function with a 256-bit digest. Thus, yescrypt's cryptographic properties are superseded by those of the ShangMi 3 hash function. This hashing method is useful in applications that need modern passphrase hashing, but have to rely on algorithms approved by the Chinese Office of State Commercial Cryptography Administration (OSCCA). The ShangMi 3 hash function has been published in Part 3: "Dedicated hash-functions" of the ISO/IEC 10118-3:2018. Acceptable for new hashes where required. Available as of 1.2.0 with libcxcrypt >= 4.5.0.

Error codes
`CRYPT_SALT_OK` (int)
  No error.
`CRYPT_SALT_INVALID` (int)
  Unknown hashing method or invalid parameters.
`CRYPT_SALT_METHOD_DISABLED` (int)
  Hashing method is no longer allowed to be used.
`CRYPT_SALT_METHOD_LEGACY` (int)
  Hashing method is no longer considered strong enough.
`CRYPT_SALT_TOO_CHEAP` (int)
  Cost parameters are considered too cheap.

Password algorithms
`PASSWORD_SHA512` (string)
  `PASSWORD_SHA512` is used to create new password hashes using the `CRYPT_PREFIX_SHA512` algorithm.
`PASSWORD_YESCRYPT` (string)
  `PASSWORD_YESCRYPT` is used to create new password hashes using the `CRYPT_PREFIX_YESCRYPT` algorithm.
`PASSWORD_SM3CRYPT` (string)
  `PASSWORD_SM3CRYPT` is used to create new password hashes using the `CRYPT_PREFIX_SM3CRYPT` algorithm. Available as of 1.2.0 with libcxcrypt >= 4.5.0.
`PASSWORD_SM3_YESCRYPT` (string)
  `PASSWORD_SM3_YESCRYPT` is used to create new password hashes using the `CRYPT_PREFIX_SM3_YESCRYPT` algorithm. Available as of 1.2.0 with libcxcrypt >= 4.5.0.

# Xpass 関数

# crypt_checksalt

(PECL xpass >= 1.1.0)

crypt_checksalt — Validate a crypt setting string

### 説明

function crypt_checksalt(string `$salt`): ?string

Checks the salt string against the system configuration and reports whether the hashing method and parameters it specifies are acceptable. It is intended to be used to determine whether the user's passphrase should be re-hashed using the currently preferred hashing method.

### パラメータ

`salt`
  Salt string to check.

### 戻り値

Returns one of the `CRYPT_SALT_*` as an int.

### 例

例1 A crypt_checksalt() example

    <?php
    // Generate a salt for a legacy method
    $salt = crypt_gensalt(CRYPT_PREFIX_STD_DES);
    // Check the salt
    $test = crypt_checksalt($salt);
    var_dump($test === CRYPT_SALT_METHOD_LEGACY);

    // Generate a salt for default method
    $salt = crypt_gensalt();
    // Check the salt
    $test = crypt_checksalt($salt);
    var_dump($test === CRYPT_SALT_OK);
    ?>

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

    bool(true)
    bool(true)

### 参考

- crypt_gensalt() - Compile a string for use as the salt argument to crypt

# crypt_gensalt

(PECL xpass >= 1.1.0)

crypt_gensalt — Compile a string for use as the salt argument to crypt

### 説明

function crypt_gensalt(string `$prefix` = `null`, int `$count` = 0): ?string

Compile a string for use as the salt argument to crypt().

### パラメータ

`prefix`
  Hashing method. One of the `CRYPT_PREFIX_*` constant. If `null`, the best available hashing method will be selected.
`count`
  Controls the processing cost of the hash; the valid range and exact meaning of count depend on the hashing method, but larger numbers correspond to more costly hashes in terms of CPU time and possibly memory usage. If count is `0`, a low default cost will be selected.

### 戻り値

Returns a string with the setting, or `null` in case of an error.

### 例

例1 A crypt_gensalt() example

    <?php
    // Generate the salt
    $salt = crypt_gensalt(CRYPT_PREFIX_BLOWFISH);
    // Hash the password
    $hash = crypt("secret", $salt);
    // Check the hash
    $test = hash_equals(crypt("secret", $hash), $hash);
    var_dump($salt, $hash, $test);
    ?>

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

    string(29) "$2y$05$GcPykP.Am8C1.dGamdpwW."
    string(60) "$2y$05$GcPykP.Am8C1.dGamdpwW.1RR.7uicWvJPZfJfCEizZHqVWwuaJLm"
    bool(true)

### 参考

- crypt_preferred_method() - Get the prefix of the preferred hash method
- crypt() - 文字列の一方向のハッシュ化を行う
- hash_equals() - タイミング攻撃に対しても安全な文字列比較

# crypt_preferred_method

(PECL xpass >= 1.1.0)

crypt_preferred_method — Get the prefix of the preferred hash method

### 説明

function crypt_preferred_method(): ?string

Get the prefix of the preferred hash method.

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns a string with the prefix, or `null` in case of an error.

### 例

例1 A crypt_preferred_method() example

    <?php
    var_dump(crypt_preferred_method());
    ?>

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

    string(3) "$y$"

### 参考

- crypt_gensalt() - Compile a string for use as the salt argument to crypt

## 目次

- crypt_checksalt — Validate a crypt setting string
- crypt_gensalt — Compile a string for use as the salt argument to crypt
- crypt_preferred_method — Get the prefix of the preferred hash method

- インストール/設定
  - 要件
  - Installation via PECL
- 定義済み定数
- Xpass 関数
  - crypt_checksalt — Validate a crypt setting string
  - crypt_gensalt — Compile a string for use as the salt argument to crypt
  - crypt_preferred_method — Get the prefix of the preferred hash method

- 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 クラス
- Xpass
  - インストール/設定
  - 定義済み定数
  - Xpass 関数

# データベース関連

# 抽象化レイヤー

# データベース (dbm 形式) 抽象化レイヤ

# はじめに

これらの関数は、Berkeley DB 型データベースへのアクセス用の基本関数を構成します。

これらの関数は、複数のファイルベースのデータベース用の抽象化レイヤです。 その機能は、» Oracle Berkeley DB でサポートされているような近代的なデータベースの 機能のサブセットに制限されています。

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定
- リソース型

## 要件

各機能の動作は、使用するデータベースの実装に依存します。 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
  デフォルトのハンドラ名。

## リソース型

PHP 8.4.0 より前のバージョンでは、 ほとんどの dba 関数はリソースを返していました。 (たとえば dba_open() は、ほとんどの dba 関数で必須の DBA リンクの識別子を、 正の整数として返していました)

# 定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

`DBA_LMDB_USE_SUB_DIR` (int)
  LMDB ドライバ用のフラグです。 サブディレクトリを作ることを許可します。 PHP 8.2.0 以降で利用可能です。
`DBA_LMDB_NO_SUB_DIR` (int)
  LMDB ドライバ用のフラグです。 サブディレクトリを作ることを許可しません。 PHP 8.2.0 以降で利用可能です。

# 例

## 目次

- 基本的な例

## 基本的な例

例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\Connection クラス

(PHP 8 >= 8.4.0)

## はじめに

PHP 8.4.0 以降、 `dba` リソースを置き換える完全不透明クラスです。

## クラス概要

namespace Dba;
final class Connection {
}

# DBA 関数

# dba_close

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_close — DBA データベースを閉じる

### 説明

function dba_close(Dba\Connection `$dba`): void

dba_close() は確立されたデータベースを閉じ、 指定したデータベースハンドルの全てのリソースを開放します。

### パラメータ

`dba`
  dba_open() または dba_popen() によって返される Dba\Connection インスタンス

### 戻り値

値を返しません。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `dba` は Dba\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、 `dba` resource を期待していました。

### 参考

- dba_open() - データベースをオープンする
- dba_popen() - データベースを持続的にオープンする

# dba_delete

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_delete — キーが指す DBA エントリを削除する

### 説明

function dba_delete(string|array `$key`, Dba\Connection `$dba`): bool

dba_delete() は、指定されたエントリを データベースから削除します。

### パラメータ

`key`
  削除するエントリのキー。
`dba`
  dba_open() または dba_popen() によって返される Dba\Connection インスタンス

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `dba` は Dba\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、 `dba` resource を期待していました。

### 参考

- dba_exists() - キーが存在するかどうかを確認する
- dba_fetch() - キーが指すデータを取得する
- dba_insert() - エントリを挿入する
- dba_replace() - エントリを置換または挿入する

# dba_exists

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_exists — キーが存在するかどうかを確認する

### 説明

function dba_exists(string|array `$key`, Dba\Connection `$dba`): bool

dba_exists() は、指定した `key` がデータベースに存在するかどうかを確認します。

### パラメータ

`key`
  確認を行うキー。
`dba`
  dba_open() または dba_popen() によって返される Dba\Connection インスタンス

### 戻り値

キーが存在する場合に `true` 、それ以外の場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `dba` は Dba\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、 `dba` resource を期待していました。

### 参考

- dba_delete() - キーが指す DBA エントリを削除する
- dba_fetch() - キーが指すデータを取得する
- dba_insert() - エントリを挿入する
- dba_replace() - エントリを置換または挿入する

# dba_fetch

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_fetch — キーが指すデータを取得する

### 説明

function dba_fetch(string|array `$key`, Dba\Connection `$dba`, int `$skip` = 0): string|false

以下はオーバーロードされているが、PHP 8.3.0 以降では推奨されないシグネチャです:

function 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() によって返される Dba\Connection インスタンス
`skip`
  cdb データベースを使用する際に無視する キー / 値 の組み合わせ数。 複数のキーに同じ名前をつけることがサポートされていないデータベースです、 この値は無視されます。

### 戻り値

キー / データの組が見つかった場合にそれに関連する文字列、 それ以外の場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `dba` は Dba\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、 `dba` resource を期待していました。
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_firstkey

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_firstkey — 最初のキーを取得する

### 説明

function dba_firstkey(Dba\Connection `$dba`): string|false

dba_firstkey() はデータベースの最初のキーを返し、 内部キーポインタをリセットします。 この関数によりデータベース全体を連続的にサーチすることが可能になります。

### パラメータ

`dba`
  dba_open() または dba_popen() によって返される Dba\Connection インスタンス

### 戻り値

成功した場合にキー、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `dba` は Dba\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、 `dba` resource を期待していました。

### 参考

- dba_nextkey() - 次のキーを取得する
- dba_key_split() - 文字列形式のキーを配列形式に分割する
- DBA の例の例 2

# dba_handlers

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

dba_handlers — 利用可能なハンドラの一覧を得る

### 説明

function 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_insert

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_insert — エントリを挿入する

### 説明

function dba_insert(string|array `$key`, string `$value`, Dba\Connection `$dba`): bool

dba_insert() は、 データベースに `key` および `value` で記述されるエントリを挿入します。

### パラメータ

`key`
  挿入するエントリのキー。もしこのキーが既にデータベースに存在する場合、 この関数は失敗します。既存のキーを置き換える場合は、 dba_replace() を使用してください。
`value`
  挿入する値。
`dba`
  dba_open() または dba_popen() によって返される Dba\Connection インスタンス

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `dba` は Dba\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、 `dba` resource を期待していました。

### 参考

- dba_exists() - キーが存在するかどうかを確認する
- dba_delete() - キーが指す DBA エントリを削除する
- dba_fetch() - キーが指すデータを取得する
- dba_replace() - エントリを置換または挿入する

# dba_key_split

(PHP 5, PHP 7, PHP 8)

dba_key_split — 文字列形式のキーを配列形式に分割する

### 説明

function dba_key_split(string|false|null `$key`): array|false

dba_key_split() は、キー（文字列形式） を配列に分割します。

### パラメータ

`key`
  文字列形式のキー。

### 戻り値

`array(0 => group, 1 => value_name)` 形式の配列を返します。 `key` が `null` あるいは `false` の場合には この関数は `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `key` に `null` または `false` を渡すことは、非推奨となりました。

### 参考

- dba_firstkey() - 最初のキーを取得する
- dba_nextkey() - 次のキーを取得する
- dba_fetch() - キーが指すデータを取得する

# dba_list

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

dba_list — オープンされている全データベースファイルのリストを得る

### 説明

function dba_list(): array

dba_list() は、オープンされている全ての データベースファイルの一覧を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

`resourceid => filename` 形式の連想配列を返します。

# dba_nextkey

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_nextkey — 次のキーを取得する

### 説明

function dba_nextkey(Dba\Connection `$dba`): string|false

dba_nextkey() は、 が指すデータベースの次のキーを返し、内部キーポインタを進めます。

### パラメータ

`dba`
  dba_open() または dba_popen() によって返される Dba\Connection インスタンス

### 戻り値

成功した場合にキー、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `dba` は Dba\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、 `dba` resource を期待していました。

### 参考

- dba_firstkey() - 最初のキーを取得する
- dba_key_split() - 文字列形式のキーを配列形式に分割する
- DBA の例の例 2

# dba_open

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_open — データベースをオープンする

### 説明

function dba_open(
string `$path`,
string `$mode`,
?string `$handler` = `null`,
int `$permission` = 0644,
int `$map_size` = 0,
?int `$flags` = `null`
): Dba\Connection|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` をサポートしています。

### 戻り値

成功した場合に Dba\Connection インスタンスを返します。 失敗した場合に `false` を返します。

### エラー / 例外

`handler` に `null` が指定されているのにデフォルトのハンドラが存在しない場合、 `E_WARNING` レベルのエラーが発生し、 `false` が返されます。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | Dba\Connection インスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。
8.2.0 | `flags` が追加されました。
8.2.0 | `handler` は、nullable になりました。
7.3.14, 7.4.2 | `lmdb` ドライバは、 `map_size` パラメータを追加でサポートしました。

### 参考

- dba_popen() - データベースを持続的にオープンする
- dba_close() - DBA データベースを閉じる

# dba_optimize

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_optimize — データベースを最適化する

### 説明

function dba_optimize(Dba\Connection `$dba`): bool

dba_optimize() は、指定されたデータベースを最適化します。

### パラメータ

`dba`
  dba_open() または dba_popen() によって返される Dba\Connection インスタンス

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `dba` は Dba\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、 `dba` resource を期待していました。

### 参考

- dba_sync() - データベースを同期する

# dba_popen

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_popen — データベースを持続的にオープンする

### 説明

function dba_popen(
string `$path`,
string `$mode`,
?string `$handler` = `null`,
int `$permission` = 0644,
int `$map_size` = 0,
?int `$flags` = `null`
): Dba\Connection|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` をサポートしています。

### 戻り値

成功した場合に Dba\Connection インスタンスを返します。 失敗した場合に `false` を返します。

### エラー / 例外

`handler` に `null` が指定されているのにデフォルトのハンドラが存在しない場合、 `E_WARNING` レベルのエラーが発生し、 `false` が返されます。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | Dba\Connection インスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。
8.2.0 | `flags` が追加されました。
8.1.0 | `handler` は、nullable になりました。
7.3.14, 7.4.2 | `lmdb` ドライバは、 `map_size` パラメータを追加でサポートしました。

### 参考

- dba_open() - データベースをオープンする
- dba_close() - DBA データベースを閉じる

# dba_replace

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_replace — エントリを置換または挿入する

### 説明

function dba_replace(string|array `$key`, string `$value`, Dba\Connection `$dba`): bool

dba_replace() は、`dba` で 指定したデータベースに `key` および `value` で記述されるエントリを 置換または挿入します。

### パラメータ

`key`
  置換するエントリのキー。
`value`
  置換される値。
`dba`
  dba_open() または dba_popen() によって返される Dba\Connection インスタンス

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `dba` は Dba\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、 `dba` resource を期待していました。

### 参考

- dba_exists() - キーが存在するかどうかを確認する
- dba_delete() - キーが指す DBA エントリを削除する
- dba_fetch() - キーが指すデータを取得する
- dba_insert() - エントリを挿入する

# dba_sync

(PHP 4, PHP 5, PHP 7, PHP 8)

dba_sync — データベースを同期する

### 説明

function dba_sync(Dba\Connection `$dba`): bool

dba_sync() は データベースを同期します。サポートされる場合には、 おそらくディスクへの物理的アクセスへのきっかけとなることでしょう。

### パラメータ

`dba`
  dba_open() または dba_popen() によって返される Dba\Connection インスタンス

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `dba` は Dba\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、 `dba` resource を期待していました。

### 参考

- dba_optimize() - データベースを最適化する

## 目次

- 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\Connection — Dba\Connection クラス
- 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 — データベースを同期する

# ODBC (Unified)

# はじめに

通常の 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 にあります。

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定
- リソース型

## 要件

サポートされるデータベースにアクセスするためには、 所定のライブラリがインストールされている必要があります。

## インストール手順

--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` (デフォルト) です。

## リソース型

PHP 8.4.0 より前のバージョンでは、 二種類のリソースを定義していました。 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

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_autocommit — 自動コミットの動作をオンまたはオフにする

### 説明

function odbc_autocommit(Odbc\Connection `$odbc`, ?bool `$enable` = `null`): int|bool

自動コミットの挙動を切り替えます。

デフォルトで接続の自動コミットはオンとなっています。自動コミットを 使用不可にするのは、トランザクションを開始することと等価です。

### パラメータ

`odbc`
  ODBC 接続オブジェクト。詳細は odbc_connect() を参照ください。
`enable`

  `enable` が `true` の場合は自動コミットが可能になり、 `false` の場合は自動コミットが使用不可になります。 `null` を渡した場合、この関数は `odbc` の自動コミットに関する状態を返します。

### 戻り値

`enable` パラメータに `null` を指定した場合、 この関数は、`odbc` に関する 自動コミットの状態を返します。自動コミットがオンの場合に 非ゼロ、オフの場合にゼロ、エラーを生じた場合に `false` を返します。

`enable` が `null` でない値の場合、 この関数は成功時に `true`、失敗したときに `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `odbc` は、Odbc\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.3.0 | `enable` は、nullable になりました。

### 参考

- odbc_commit() - ODBC トランザクションをコミットする
- odbc_rollback() - トランザクションをロールバックする

# odbc_binmode

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_binmode — バイナリカラムデータを処理する

### 説明

function odbc_binmode(Odbc\Result `$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`

  ODBC 結果オブジェクト

`mode`

  `mode` には、以下の値が指定できます。

  - `ODBC_BINMODE_PASSTHRU`: BINARY データとして通過
  - `ODBC_BINMODE_RETURN`: そのまま返す
  - `ODBC_BINMODE_CONVERT`: char に変換し返す

  > 注意: LONGVARBINARY 型のカラムを処理する方法は odbc_longreadlen() によっても影響を受けます。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `statement` は、Odbc\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

# odbc_close

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_close — ODBC 接続を閉じる

### 説明

function odbc_close(Odbc\Connection `$odbc`): void

指定された接続 ID が指すデータベースサーバーへの接続を閉じます。

### パラメータ

`odbc`
  ODBC 接続オブジェクト。詳細は odbc_connect() を参照ください。

### 戻り値

値を返しません。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `odbc` は、Odbc\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 注意

> 注意:

> この関数の処理は、この接続に関してオープンされたトランザクションがある場合に失敗します。 この場合、接続はオープンされたままとなります。

# odbc_close_all

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_close_all — 全ての ODBC 接続を閉じる

### 説明

function odbc_close_all(): void

odbc_close_all()は、 データベースサーバーへの全ての接続を閉じます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

値を返しません。

### 注意

> 注意:

> この関数は、ある接続においてオープンされたトランザクションがある場合に失敗します。 この場合、この接続はオープンされたままとなります。

# odbc_columnprivileges

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_columnprivileges — 指定したテーブルに関するカラムおよび付随する権限のリストを取得する

### 説明

function odbc_columnprivileges(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`,
string `$column`
): Odbc\Result|false

指定したテーブルに関するカラムおよび付随する権限のリストを取得します。

### パラメータ

`odbc`
  ODBC 接続オブジェクト。詳細は odbc_connect() を参照ください。
`catalog`

  カタログ(ODBC 2 の用語では '修飾子')。

`schema`

  スキーマ (ODBC 2 の用語では '所有者')。 このパラメータには以下の検索パターンを使用できます。 `%` はゼロ個以上の文字にマッチし、 `_` はひとつの文字にマッチします。

`table`

  テーブル名。 このパラメータには以下の検索パターンを使用できます。 `%` はゼロ個以上の文字にマッチし、 `_` はひとつの文字にマッチします。

`column`

  カラム名。 このパラメータには以下の検索パターンを使用できます。 `%` はゼロ個以上の文字にマッチし、 `_` はひとつの文字にマッチします。

### 戻り値

ODBC 結果オブジェクトを返します。失敗した場合に `false` を返します。 この結果オブジェクトを使用して、カラムや関連する権限の一覧を取得します。

結果は以下のカラムを有します。

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `COLUMN_NAME`
- `GRANTOR`
- `GRANTEE`
- `PRIVILEGE`
- `IS_GRANTABLE`

ドライバは追加のカラムを返すことが出来ます。

結果セットは `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME`, `COLUMN_NAME`, `PRIVILEGE` でソートされます。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `odbc` は、Odbc\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_columns

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_columns — 指定したテーブルにあるカラム名のリストを取得する

### 説明

function odbc_columns(
Odbc\Connection `$odbc`,
?string `$catalog` = `null`,
?string `$schema` = `null`,
?string `$table` = `null`,
?string `$column` = `null`
): Odbc\Result|false

指定したテーブルにあるカラム名のリストを取得します。

### パラメータ

`odbc`
  ODBC 接続オブジェクト。詳細は odbc_connect() を参照ください。
`catalog`

  カタログ(ODBC 2 の用語では '修飾子')。

`schema`

  スキーマ (ODBC 2 の用語では '所有者')。 このパラメータには以下の検索パターンを使用できます。 `%` はゼロ個以上の文字にマッチし、 `_` はひとつの文字にマッチします。

`table`

  テーブル名。 このパラメータには以下の検索パターンを使用できます。 `%` はゼロ個以上の文字にマッチし、 `_` はひとつの文字にマッチします。

`column`

  カラム名。 このパラメータには以下の検索パターンを使用できます。 `%` はゼロ個以上の文字にマッチし、 `_` はひとつの文字にマッチします。

### 戻り値

ODBC 結果オブジェクトを返します。失敗した場合に `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.4.0 | 引数 `odbc` は、Odbc\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
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_commit

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_commit — ODBC トランザクションをコミットする

### 説明

function odbc_commit(Odbc\Connection `$odbc`): bool

その接続におけるすべての実行中のトランザクションをコミットします。

### パラメータ

`odbc`
  ODBC 接続オブジェクト。詳細は odbc_connect() を参照ください。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `odbc` は、Odbc\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

# odbc_connect

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_connect — データソースに接続する

### 説明

function odbc_connect(
string `$dsn`,
?string `$user` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
int `$cursor_option` = `SQL_CUR_USE_DRIVER`
): Odbc\Connection|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`

  ユーザー名。 `dsn` に `uid` が含まれている場合、このパラメータは無視されます。 `user` を指定せずに接続する場合、`null` を指定します。

`password`

  パスワード。 `dsn` に `pwd` が含まれている場合、このパラメータは無視されます。 `password` を指定せずに接続する場合、`null` を指定します。

`cursor_option`

  この接続で使用するカーソルの型。 通常はこのパラメータは必要ありませんが、いくつかの ODBC ドライバの問題に対処する際には有用です。

  次のような定数がカーソル型として定義されています。

  - SQL_CUR_USE_IF_NEEDED
  - SQL_CUR_USE_ODBC
  - SQL_CUR_USE_DRIVER

### 戻り値

ODBC 接続を返します。 失敗した場合に `false` を返します

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | この関数は Odbc\Connection クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。
8.4.0 | `user` および `password` が nullable となりました。 また、省略できるようになり、デフォルトでは `null` となるようになりました。
8.4.0 | 以前のバージョンでは、`password` に空文字列を指定した場合、 `dsn` に対して生成される接続文字列に `pwd` が含まれていませんでした。 このバージョンからは、空文字列が値に指定された `pwd` を含んだ状態で生成されるようになりました。 以前の挙動に戻したい場合は、`password` に `null` を指定してください。
8.4.0 | 以前のバージョンでは、`dsn` に `uid` または `pwd` のいずれかが含まれていると、 `user` および `password` の両方が常に無視されていました。 このバージョンからは、`dsn` に `uid` が含まれている場合にのみ `user` が無視され、 `dsn` に `pwd` が含まれている場合にのみ `password` が無視されるようになりました。

### 例

例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_connection_string_is_quoted

(PHP 8 >= 8.2.0)

odbc_connection_string_is_quoted — ODBC の接続文字列の値が、クオートされているかを調べる

### 説明

function 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_connection_string_quote

(PHP 8 >= 8.2.0)

odbc_connection_string_quote — ODBC の接続文字列をクオートする

### 説明

function 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_connection_string_should_quote

(PHP 8 >= 8.2.0)

odbc_connection_string_should_quote — ODBC の接続文字列を、クオートすべきかを調べる

### 説明

function 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_cursor

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_cursor — カーソル名を得る

### 説明

function odbc_cursor(Odbc\Result `$statement`): string|false

指定された接続 ID に関するカーソル名を返します。 Gets the cursorname for the given result_id.

### パラメータ

`statement`

  ODBC 結果オブジェクト

### 戻り値

カーソル名を文字列で返します。 失敗した場合に `false` を返します

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `statement` は、Odbc\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

# odbc_data_source

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

odbc_data_source — 利用可能なDSNについての情報を返す

### 説明

function odbc_data_source(Odbc\Connection `$odbc`, int `$fetch_type`): array|null|false

この関数は、有効な DSN（複数回のコールの後）のリストを返します。

### パラメータ

`odbc`
  ODBC 接続オブジェクト。詳細は odbc_connect() を参照ください。
`fetch_type`

  `fetch_type` は次のふたつの定数 `SQL_FETCH_FIRST`, `SQL_FETCH_NEXT` のうちのどちらかです。 この関数を最初にコールする際には `SQL_FETCH_FIRST` を、それ以降は `SQL_FETCH_NEXT` を使用します。

### 戻り値

エラー時には `false`、成功時には配列を返します。 最後の利用可能なDSNを取得した後は、`null` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `odbc` は、Odbc\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_do

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_do — odbc_exec() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 odbc_exec().

# odbc_error

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_error — 直近のエラーコードを得る

### 説明

function odbc_error(?Odbc\Connection `$odbc` = `null`): string

6 桁の ODBC ステートを返します。エラーがない場合には、空の文字列を返します。

### パラメータ

`odbc`
  ODBC 接続オブジェクト。詳細は odbc_connect() を参照ください。

### 戻り値

`odbc` が指定された場合、 その接続の直近の状態が返されます。そうでない場合、 他の接続の直近の状態が返されます。

この関数の戻り値が意味を持つのは、直近の odbc クエリが失敗した場合 (すなわち odbc_exec() が `false` を返した場合) のみです。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `odbc` は、Odbc\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.0.0 | `odbc` は、nullable になりました。

### 参考

- odbc_errormsg() - 直近のエラーメッセージを得る
- odbc_exec() - SQL文を直接実行する

# odbc_errormsg

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_errormsg — 直近のエラーメッセージを得る

### 説明

function odbc_errormsg(?Odbc\Connection `$odbc` = `null`): string

直近の ODBC エラーメッセージを含む文字列を返します。 エラーが発生していない場合は、空の文字列を返します。

### パラメータ

`odbc`
  ODBC 接続オブジェクト。詳細は odbc_connect() を参照ください。

### 戻り値

`odbc` が指定された場合、 その接続の直近の状態が返されます。さもなくば、他の接続の直近の状態が返されます。

この関数の戻り値が意味を持つのは、直近の odbc クエリが失敗した場合 (すなわち odbc_exec() が `false` を返した場合) のみです。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `odbc` は、Odbc\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.0.0 | `odbc` は、nullable になりました。

### 参考

- odbc_error() - 直近のエラーコードを得る
- odbc_exec() - SQL文を直接実行する

# odbc_exec

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_exec — SQL文を直接実行する

### 説明

function odbc_exec(Odbc\Connection `$odbc`, string `$query`): Odbc\Result|false

SQL 命令を データベースサーバーに送ります。

### パラメータ

`odbc`
  ODBC 接続オブジェクト。詳細は odbc_connect() を参照ください。
`query`

  SQL 文。

### 戻り値

SQL コマンドの実行に成功した場合には、 ODBC 結果オブジェクトを返します。エラー時には、`false`を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `odbc` は、Odbc\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.4.0 | この関数は Odbc\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。
8.0.0 | `flags` は削除されました。

### 参考

- odbc_prepare() - 実行用に文を準備する
- odbc_execute() - プリペアドステートメントを実行する

# odbc_execute

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_execute — プリペアドステートメントを実行する

### 説明

function odbc_execute(Odbc\Result `$statement`, array `$params` = []): bool

odbc_prepare() で準備された命令を実行します。

### パラメータ

`statement`

  odbc_prepare() で取得した ODBC 結果オブジェクト

`params`

  プリペアドステートメントの中のプレースホルダが、 `params` 内のパラメータで順に置き換えられます。 この関数をコールした際に、配列の要素は文字列に変換されます。

  `params` の中でシングルクォートで括られたデータがある場合、 それはファイル名と解釈されます。そのファイルの内容が、 該当するプレースホルダのデータとしてデータベースサーバーに送信されます。

  シングルクォートで括られたデータを純粋に文字列として使用したい場合は、 空白などの別の文字を前後に付加する必要があります。 それにより、パラメータがファイル名とみなされることがなくなります (もしこのオプションが不要なら、別の仕組み、たとえば odbc_exec() で直接クエリを実行するなどを使用する必要があります)。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | この関数は Odbc\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。
8.0.0 | The unused `flags` parameter was removed.

### 例

例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_fetch_array

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

odbc_fetch_array — 連想配列として結果の行を取得する

### 説明

function odbc_fetch_array(Odbc\Result `$statement`, ?int `$row` = `null`): array|false

ODBC クエリから、連想配列を取得します。

### パラメータ

`statement`

  odbc_exec() の ODBC 結果オブジェクト

`row`

  どの行番号を取得するのかを任意で指定する。

### 戻り値

取得した行に対応する配列を返します。もう行がない場合には `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `statement` は、Odbc\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.4.0 | `row` is now nullable.

### 注意

> 注意: この関数は、DBMaker、IBM DB2 あるいは UnixODBC のサポートを有効にして コンパイルした場合に使用可能です。

### 参考

- odbc_fetch_row() - 行を取り込む
- odbc_fetch_object() - オブジェクトとして結果の行を取得する
- odbc_num_rows() - 結果における行数を返す

# odbc_fetch_into

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_fetch_into — 一行ぶんの結果を配列に取り込む

### 説明

function odbc_fetch_into(Odbc\Result `$statement`, array `&$array`, ?int `$row` = `null`): int|false

結果の行を array に取得します。

### パラメータ

`statement`

  ODBC 結果オブジェクト

`array`

  結果の配列。型変換によってい配列型となるので、どんな型であっても構いません。 この配列には、添字 0 から始まるカラム番号が代入されます。

`row`

  行番号。

### 戻り値

結果におけるカラム番号を返します。また、エラーの場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `statement` は、Odbc\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.4.0 | `row` is now nullable.

### 例

例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_object

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

odbc_fetch_object — オブジェクトとして結果の行を取得する

### 説明

function odbc_fetch_object(Odbc\Result `$statement`, ?int `$row` = `null`): stdClass|false

ODBC クエリから、オブジェクトを取得します。

### パラメータ

`statement`

  odbc_exec() の ODBC 結果オブジェクト

`row`

  どの行番号を取得するのかを任意で指定する。

### 戻り値

取得した行に対応するオブジェクトを返します。もう行がない場合には `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `statement` は、Odbc\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.4.0 | `row` is now nullable.

### 注意

> 注意: この関数は、DBMaker、IBM DB2 あるいは UnixODBC のサポートを有効にして コンパイルした場合に使用可能です。

### 参考

- odbc_fetch_row() - 行を取り込む
- odbc_fetch_array() - 連想配列として結果の行を取得する
- odbc_num_rows() - 結果における行数を返す

# odbc_fetch_row

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_fetch_row — 行を取り込む

### 説明

function odbc_fetch_row(Odbc\Result `$statement`, ?int `$row` = `null`): bool

odbc_do() や odbc_exec() から返された行データを取得します。 odbc_fetch_row() がコールされた後、この行のフィールドは、 odbc_result() でアクセス可能となります。

### パラメータ

`statement`

  ODBC 結果オブジェクト

`row`

  `row` が指定されない場合、 odbc_fetch_row() は、 結果セットにおける次の行を取り込もうと試みます。 `row` を指定した odbc_fetch_row() のコールと指定しないコールを混用することができます。

  結果を複数回走査したい場合、odbc_fetch_row() を `row` に 1 を指定してコールし、 続いて結果を再度見るために `row` を指定せずに odbc_fetch_row() を実行しつづけます。 行を番号で取り込むことをドライバがサポートしていない場合、 `row` パラメータは無視されます。

### 戻り値

行があった場合には `true`、それ以外の場合に `false` を返します。

### エラー / 例外

`row` が0以下の場合、 `E_WARNING` が発生します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `statement` は、Odbc\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.4.0 | `row` が0以下の場合、 `E_WARNING` が発生するようになりました。
8.0.0 | `row` は、nullable になりました。

# odbc_field_len

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_len — フィールドの長さ (精度) を得る

### 説明

function odbc_field_len(Odbc\Result `$statement`, int `$field`): int|false

指定した ODBC 結果 ID の番号で参照されるフィールドの長さを取得します。

### パラメータ

`statement`

  ODBC 結果オブジェクト

`field`

  フィールド番号。フィールド番号は 1 から始まります。

### 戻り値

フィールドの長さ、あるいはエラー時に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `statement` は、Odbc\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 参考

- 浮動小数点の精度を得るには odbc_field_scale() - フィールドの精度を得る

# odbc_field_name

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_name — カラム名を得る

### 説明

function odbc_field_name(Odbc\Result `$statement`, int `$field`): string|false

指定された ODBC 結果オブジェクト において指定されたカラム番号にあるフィールドの名前を取得します。

### パラメータ

`statement`

  ODBC 結果オブジェクト

`field`

  フィールド番号。フィールド番号は、1 から始まります。

### 戻り値

フィールド名を表す文字列、あるいはエラー時に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `statement` は、Odbc\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

# odbc_field_num

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_num — カラム番号を返す

### 説明

function odbc_field_num(Odbc\Result `$statement`, string `$field`): int|false

指定したODBC 結果オブジェクト におけるフィールド名に対応するカラムスロットの数を取得します。

### パラメータ

`statement`

  ODBC 結果オブジェクト

`field`

  フィールド名。

### 戻り値

フィールド番号、あるいはエラー時に `false` を返します。 フィールド番号は、1 から始まります。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `statement` は、Odbc\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

# 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_scale

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_scale — フィールドの精度を得る

### 説明

function odbc_field_scale(Odbc\Result `$statement`, int `$field`): int|false

指定した ODBC 結果 ID の番号で指定したフィールドの精度を取得します。

### パラメータ

`statement`

  ODBC 結果オブジェクト

`field`

  フィールド番号。 フィールド番号は、1 から始まります。

### 戻り値

フィールドの精度を整数値で返します。 エラー時に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `statement` は、Odbc\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

# odbc_field_type

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_field_type — フィールドのデータ型を返す

### 説明

function odbc_field_type(Odbc\Result `$statement`, int `$field`): string|false

指定された ODBC 結果 ID において指定番号で参照されるフィールドの SQL 型を取得します。

### パラメータ

`statement`

  ODBC 結果オブジェクト

`field`

  フィールド番号。フィールド番号は 1 から始まります。

### 戻り値

フィールドの型を表す文字列、あるいはエラー時に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `statement` は、Odbc\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

# odbc_foreignkeys

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_foreignkeys — 外部キーのリストを取得する

### 説明

function odbc_foreignkeys(
Odbc\Connection `$odbc`,
?string `$pk_catalog`,
string `$pk_schema`,
string `$pk_table`,
string `$fk_catalog`,
string `$fk_schema`,
string `$fk_table`
): Odbc\Result|false

指定したテーブルの外部キーのリスト、 または指定したテーブルの主キーを参照する他のテーブルの外部キーのリストを取得します。

### パラメータ

`odbc`
  ODBC 接続オブジェクト。詳細は odbc_connect() を参照ください。
`pk_catalog`

  主キーテーブルのカタログ (ODBC 2 の用語では '修飾子')

`pk_schema`

  主キーテーブルのスキーマ(ODBC 2 の用語では '所有者')

`pk_table`

  主キーのテーブル。

`fk_catalog`

  外部キーテーブルのカタログ (ODBC 2 の用語では '修飾子')

`fk_schema`

  外部キーテーブルのスキーマ(ODBC 2 の用語では '所有者')

`fk_table`

  外部キーのテーブル。

### 戻り値

ODBC 結果オブジェクトを返します。失敗した場合に `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` で指定されたテーブルの外部キーを返します。 返されるキーは最大でも一つだけです。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `odbc` は、Odbc\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.4.0 | この関数は Odbc\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。

### 参考

- odbc_tables() - 指定したデータソースに保存されたテーブルの名前のリストを取得する
- odbc_primarykeys() - テーブルの主キーを取得する

# odbc_free_result

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_free_result — 結果を保持するオブジェクトを開放する

### 説明

function odbc_free_result(Odbc\Result `$statement`): true

結果を保持するオブジェクトを開放します。

odbc_free_result()は、スクリプトのメモリ消費量が 多すぎることが懸念される場合にのみコールする必要があります。 全ての結果保持用メモリは、スクリプト実行が終了した際に自動的に開放されます。

### パラメータ

`statement`

  ODBC 結果オブジェクト

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `statement` は、Odbc\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 注意

> 注意:

> 自動コミットが無効（odbc_autocommit() を 参照ください）な時にコミットの前に odbc_free_result() をコールすると、全ての 未解決のトランザクションは、ロールバックされます。

# odbc_gettypeinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_gettypeinfo — データソースがサポートするデータ型についての情報を取得する

### 説明

function odbc_gettypeinfo(Odbc\Connection `$odbc`, int `$data_type` = 0): Odbc\Result|false

データソースがサポートするデータ型についての情報を取得します。

### パラメータ

`odbc`
  ODBC 接続オブジェクト。詳細は odbc_connect() を参照ください。
`data_type`

  データ型。単一のデータ型に情報を制限するために使用します。

### 戻り値

ODBC 結果オブジェクトを返します。失敗した場合に `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 でソートされます。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `odbc` は、Odbc\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.4.0 | この関数は Odbc\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。

# odbc_longreadlen

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_longreadlen — LONG カラムを処理する

### 説明

function odbc_longreadlen(Odbc\Result `$statement`, int `$length`): true

LONG および LONGVARBINARY のカラムを処理する方法を制御します。 デフォルトの長さは、php.ini の uodbc.defaultlrl 経由で設定できます。

### パラメータ

`statement`

  ODBC 結果オブジェクト

`length`

  PHP に返されるバイト数は、パラメータ length により制御されます。 これを `0` をセットした場合、ロングカラムデータは、 odbc_result() で取得する際に、クライアントにそのまま渡されます(つまり、表示されます)。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `statement` は、Odbc\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 注意

> 注意:

> `LONGVARBINARY` カラムの処理は、odbc_binmode() にも影響を受けます。

# odbc_next_result

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

odbc_next_result — 複数の結果が利用可能などうか確認する

### 説明

function odbc_next_result(Odbc\Result `$statement`): bool

まだ結果セットが存在して odbc_fetch_array()、odbc_fetch_row()、 odbc_result() などで次の結果セットにアクセスできるかどうかを調べます。

### パラメータ

`statement`

  ODBC 結果オブジェクト

### 戻り値

結果セットがまだある場合に `true`、それ以外の場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `statement` は、Odbc\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_num_fields

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_num_fields — 結果のカラム数を返す

### 説明

function odbc_num_fields(Odbc\Result `$statement`): int

ODBC 結果におけるフィールド (カラム) の数を取得します。

### パラメータ

`statement`

  odbc_exec() が返す ODBC 結果オブジェクト

### 戻り値

フィールド数、あるいはエラー時に -1 を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `statement` は、Odbc\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

# odbc_num_rows

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_num_rows — 結果における行数を返す

### 説明

function odbc_num_rows(Odbc\Result `$statement`): int

ODBC 結果における行の数を取得します。 INSERT、UPDATE および DELETE 命令に関しては、 odbc_num_rows() は、変更された行の数を返します。 SELECT 文の場合、この関数は利用可能な行の数を返します。

### パラメータ

`statement`

  odbc_exec() が返す ODBC 結果オブジェクト

### 戻り値

ODBC 結果における行の数を返します。 この関数は、エラー時に-1を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `statement` は、Odbc\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 注意

> 注意:

> SELECT の後に利用可能な行の数を定義するために odbc_num_rows() を使用した場合、 多くのドライバにおいて、-1 が返されます。

# odbc_pconnect

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_pconnect — 持続的なデータベース接続を開く

### 説明

function odbc_pconnect(
string `$dsn`,
?string `$user` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
int `$cursor_option` = `SQL_CUR_USE_DRIVER`
): Odbc\Connection|false

持続的なデータベース接続を開きます。

この関数は odbc_connect() に非常に似ていますが、 スクリプトが終了した時に接続が閉じられないという点が異なります。 同じ `dsn`、`user`、 `password` の組み合わせ （odbc_connect() および odbc_pconnect() による）接続の場合は、 持続的な接続を再利用することが可能です。

### パラメータ

詳細は odbc_connect() を参照ください。

### 戻り値

ODBC 接続 ID を返します。 失敗した場合に `false` を返します

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | この関数は Odbc\Connection クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。
8.4.0 | `user` および `password` が nullable となりました。 また、省略できるようになり、デフォルトでは `null` となるようになりました。
8.4.0 | 以前のバージョンでは、`password` に空文字列を指定した場合、 `dsn` に対して生成される接続文字列に `pwd` が含まれていませんでした。 このバージョンからは、空文字列が値に指定された `pwd` を含んだ状態で生成されるようになりました。 以前の挙動に戻したい場合は、`password` に `null` を指定してください。
8.4.0 | 以前のバージョンでは、`dsn` に `uid` または `pwd` のいずれかが含まれていると、 `user` および `password` の両方が常に無視されていました。 このバージョンからは、`dsn` に `uid` が含まれている場合にのみ `user` が無視され、 `dsn` に `pwd` が含まれている場合にのみ `password` が無視されるようになりました。

### 注意

> 注意: 持続的な接続は、PHP を CGI プログラムとして使用する場合には使用できません。

### 参考

- odbc_connect() - データソースに接続する
- 持続的データベース接続

# odbc_prepare

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_prepare — 実行用に文を準備する

### 説明

function odbc_prepare(Odbc\Connection `$odbc`, string `$query`): Odbc\Result|false

実行用に文を準備します。 ODBC 結果オブジェクト は、この後 odbc_execute() で命令を実行する際に使用することができます。

(IBM DB2、MS SQL Server および Oracle のように) ストアドプロシージャが利用可能で、ODBC 仕様で定義されている IN、INOUT および OUT が利用できるものもあります。 しかし、Unified ODBC ドライバでは現在 IN 型のパラメータしかサポートしていません。

### パラメータ

`odbc`
  ODBC 接続オブジェクト。詳細は odbc_connect() を参照ください。
`query`

  準備するクエリ文字列。

### 戻り値

SQL コマンドの準備に成功した場合は、ODBC 結果オブジェクトを返します。 エラー時には、`false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `odbc` は、Odbc\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.4.0 | この関数は Odbc\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。

### 例

例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_primarykeys

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_primarykeys — テーブルの主キーを取得する

### 説明

function odbc_primarykeys(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`
): Odbc\Result|false

テーブルの主キーを有するカラムの名前を取得する際に使用可能な結果オブジェクトを返します。

### パラメータ

`odbc`
  ODBC 接続オブジェクト。詳細は odbc_connect() を参照ください。
`catalog`

  カタログ(ODBC 2 の用語では '修飾子')。

`schema`

  スキーマ (ODBC 2 の用語では '所有者')。

`table`

### 戻り値

ODBC 結果オブジェクトを返します。失敗した場合に `false` を返します。

結果は以下のカラムを有します。

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `COLUMN_NAME`
- `KEY_SEQ`
- `PK_NAME`

ドライバは追加のカラムを返すことが出来ます。

結果セットは `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME`, `KEY_SEQ` でソートされます。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `odbc` は、Odbc\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.4.0 | この関数は Odbc\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。

### 例

例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_procedurecolumns

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_procedurecolumns — プロシージャへのパラメータに関する情報を取得する

### 説明

function odbc_procedurecolumns(
Odbc\Connection `$odbc`,
?string `$catalog` = `null`,
?string `$schema` = `null`,
?string `$procedure` = `null`,
?string `$column` = `null`
): Odbc\Result|false

プロシージャへのパラメータに関する情報を取得します。

### パラメータ

`odbc`
  ODBC 接続オブジェクト。詳細は odbc_connect() を参照ください。
`catalog`

  カタログ(ODBC 2 の用語では '修飾子')。

`schema`

  スキーマ (ODBC 2 の用語では '所有者')。 このパラメータには以下の検索パターンを使用できます。 `%` はゼロ個以上の文字にマッチし、 `_` はひとつの文字にマッチします。

`procedure`

  プロシージャ。 このパラメータには以下の検索パターンを使用できます。 `%` はゼロ個以上の文字にマッチし、 `_` はひとつの文字にマッチします。

`column`

  カラム。 このパラメータには以下の検索パターンを使用できます。 `%` はゼロ個以上の文字にマッチし、 `_` はひとつの文字にマッチします。

### 戻り値

指定したプロシージャに関して入出力パラメータのリストとその結果を構成するカラムを返します。 ODBC 結果オブジェクトを返します。失敗した場合に `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.4.0 | 引数 `odbc` は、Odbc\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.4.0 | この関数は Odbc\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。
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_procedures

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_procedures — 指定したデータソースに保存されているプロシージャのリストを取得する

### 説明

function odbc_procedures(
Odbc\Connection `$odbc`,
?string `$catalog` = `null`,
?string `$schema` = `null`,
?string `$procedure` = `null`
): Odbc\Result|false

指定した範囲の全てのプロシージャのリストを取得します。

### パラメータ

`odbc`
  ODBC 接続オブジェクト。詳細は odbc_connect() を参照ください。
`catalog`

  カタログ(ODBC 2 の用語では '修飾子')。

`schema`

  スキーマ (ODBC 2 の用語では '所有者')。 このパラメータには以下の検索パターンを使用できます。 `%` はゼロ個以上の文字にマッチし、 `_` はひとつの文字にマッチします。

`procedure`

  名前。 このパラメータには以下の検索パターンを使用できます。 `%` はゼロ個以上の文字にマッチし、 `_` はひとつの文字にマッチします。

### 戻り値

情報を含むODBC 結果オブジェクトを返します。失敗した場合に `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.4.0 | 引数 `odbc` は、Odbc\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.4.0 | この関数は Odbc\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。
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_result

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_result — 結果データを得る

### 説明

function odbc_result(Odbc\Result `$statement`, string|int `$field`): string|bool|null

結果データを取得します。

### パラメータ

`statement`

  ODBC 結果オブジェクト

`field`

  取得するフィールド。 カラム番号を表す整数またはフィールド名を表す文字列のどちらを指定できます。

### 戻り値

フィールドの内容を表す文字列を返します。エラー時には `false`、NULL データの場合は `null`、そしてバイナリデータの場合は `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `statement` は、Odbc\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

最初の 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() を参照ください。

# odbc_result_all

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_result_all — HTML テーブルとして結果を出力する

警告

この関数は PHP 8.1.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

function odbc_result_all(Odbc\Result `$statement`, string `$format` = ""): int|false

odbc_exec() により作成された結果オブジェクト から全ての行を出力します。結果は、HTML テーブル形式で出力されます。 データはエスケープされません。

この関数は、本番環境で使うことを想定していません。 つまり、開発中に結果セットを素早く描画させるためだけに使うものだということです。

### パラメータ

`statement`

  ODBC 結果オブジェクト

`format`

  テーブルのフォーマット指定。

### 戻り値

成功の場合に結果の行数、エラーの場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `statement` は、Odbc\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.1.0 | この関数は、推奨されなくなりました。

# odbc_rollback

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_rollback — トランザクションをロールバックする

### 説明

function odbc_rollback(Odbc\Connection `$odbc`): bool

この接続における全ての未解決の命令をロールバックします。

### パラメータ

`odbc`
  ODBC 接続オブジェクト。詳細は odbc_connect() を参照ください。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `odbc` は、Odbc\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

# odbc_setoption

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_setoption — ODBC の設定を変更する

### 説明

function odbc_setoption(
Odbc\Connection|Odbc\Result `$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` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `odbc` expects an Odbc\Connection or an Odbc\Result instance now; previously, a resource was expected.

### 例

例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_specialcolumns

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_specialcolumns — 特殊カラムを取得する

### 説明

function odbc_specialcolumns(
Odbc\Connection `$odbc`,
int `$type`,
?string `$catalog`,
string `$schema`,
string `$table`,
int `$scope`,
int `$nullable`
): Odbc\Result|false

テーブルのレコードを特定する最適なカラムの組合せ、 またはレコードの値がトランザクションにより更新される際に自動的に更新されるカラムを取得します。

### パラメータ

`odbc`
  ODBC 接続オブジェクト。詳細は 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 結果オブジェクトを返します。失敗した場合に `false` を返します。

結果セットのカラムは次のようになります。

- `SCOPE`
- `COLUMN_NAME`
- `DATA_TYPE`
- `TYPE_NAME`
- `COLUMN_SIZE`
- `BUFFER_LENGTH`
- `DECIMAL_DIGITS`
- `PSEUDO_COLUMN`

ドライバは追加のカラムを返すことが出来ます。

結果セットは `SCOPE` でソートされます。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `odbc` は、Odbc\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.4.0 | この関数は Odbc\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。

### 参考

- odbc_tables() - 指定したデータソースに保存されたテーブルの名前のリストを取得する

# odbc_statistics

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_statistics — テーブルに関する統計情報を取得する

### 説明

function odbc_statistics(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`,
int `$unique`,
int `$accuracy`
): Odbc\Result|false

テーブルおよびインデックスに関する統計情報を取得します。

### パラメータ

`odbc`
  ODBC 接続オブジェクト。詳細は odbc_connect() を参照ください。
`catalog`

  カタログ(ODBC 2 の用語では '修飾子')。

`schema`

  スキーマ (ODBC 2 の用語では '所有者')。

`table`

  テーブル名。

`unique`

  インデックスのタイプ。 `SQL_INDEX_UNIQUE`, `SQL_INDEX_ALL` のいずれかを指定します。

`accuracy`

  `SQL_ENSURE`, `SQL_QUICK` のいずれかを指定します。 後者は、サーバーで利用できる場合に限り、`CARDINALITY` と `PAGES` をドライバが取得するように要求します。

### 戻り値

ODBC 結果オブジェクトを返します。失敗した場合に `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` でソートされます。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `odbc` は、Odbc\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.4.0 | この関数は Odbc\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。

### 例

例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_tableprivileges

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_tableprivileges — 各テーブルのリストおよび関連する権限のリストを取得する

### 説明

function odbc_tableprivileges(
Odbc\Connection `$odbc`,
?string `$catalog`,
string `$schema`,
string `$table`
): Odbc\Result|false

指定した範囲にあるテーブルおよび各テーブルに関連する権限のリストを取得します。

### パラメータ

`odbc`
  ODBC 接続オブジェクト。詳細は odbc_connect() を参照ください。
`catalog`

  カタログ(ODBC 2 の用語では '修飾子')。

`schema`

  スキーマ (ODBC 2 の用語では '所有者')。 このパラメータには以下の検索パターンを使用できます。 `%` はゼロ個以上の文字にマッチし、 `_` はひとつの文字にマッチします。

`table`

  名前。 このパラメータには以下の検索パターンを使用できます。 `%` はゼロ個以上の文字にマッチし、 `_` はひとつの文字にマッチします。

### 戻り値

ODBC 結果オブジェクトを返します。失敗した場合に `false` を返します。

結果セットのカラムは次のようになります。

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `GRANTOR`
- `GRANTEE`
- `PRIVILEGE`
- `IS_GRANTABLE`

ドライバは追加のカラムを返すことが出来ます。

結果セットは `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME`, `PRIVILEGE`, `GRANTEE` でソートされます。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `odbc` は、Odbc\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.4.0 | この関数は Odbc\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。

### 例

例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_tables

(PHP 4, PHP 5, PHP 7, PHP 8)

odbc_tables — 指定したデータソースに保存されたテーブルの名前のリストを取得する

### 説明

function odbc_tables(
Odbc\Connection `$odbc`,
?string `$catalog` = `null`,
?string `$schema` = `null`,
?string `$table` = `null`,
?string `$types` = `null`
): Odbc\Result|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 接続オブジェクト。詳細は odbc_connect() を参照ください。
`catalog`

  カタログ(ODBC 2 の用語では '修飾子')。

`schema`

  スキーマ (ODBC 2 の用語では '所有者')。 このパラメータには以下の検索パターンを使用できます。 `%` はゼロ個以上の文字にマッチし、 `_` はひとつの文字にマッチします。

`table`

  名前。 このパラメータには以下の検索パターンを使用できます。 `%` はゼロ個以上の文字にマッチし、 `_` はひとつの文字にマッチします。

`types`

  `table_type` が空の文字列ではない場合、検索する型に ついてカンマで区切った値のリストを指定する必要があります。 各値は、シングルクオート(`'`)で括るかまたは括らない形で指定可能です。 例えば、`'TABLE','VIEW'` または `TABLE, VIEW` となります。 データソースが指定したテーブル型をサポートしていない場合、 odbc_tables() はその型についていかなる結果も 返しません。

### 戻り値

情報を含んでいる ODBC 結果オブジェクトを返します。 失敗した場合に `false` を返します。

結果セットのカラムは次のようになります。

- `TABLE_CAT`
- `TABLE_SCHEM`
- `TABLE_NAME`
- `TABLE_TYPE`
- `REMARKS`

ドライバは追加のカラムを返すことが出来ます。

結果セットは `TABLE_TYPE`, `TABLE_CAT`, `TABLE_SCHEM`, `TABLE_NAME` でソートされます。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 引数 `odbc` は、Odbc\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.4.0 | この関数は Odbc\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。
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() - 指定したデータソースに保存されているプロシージャのリストを取得する

## 目次

- 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\Connection クラス

(PHP 8 >= 8.4.0)

## はじめに

PHP 8.4.0 以降、`odbc_connection` resource を置き換える完全不透明クラスです。

## クラス概要

namespace Odbc;
class Connection {
}

# Odbc\Result クラス

(PHP 8 >= 8.4.0)

## はじめに

PHP 8.4.0 以降、`odbc_result` resource を置き換える完全不透明クラスです。

## クラス概要

namespace Odbc;
class Result {
}

- インストール/設定
  - 要件
  - インストール手順
  - 実行時設定
  - リソース型
- 定義済み定数
- 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\Connection — Odbc\Connection クラス
- Odbc\Result — Odbc\Result クラス

# PHP Data Objects

# はじめに

`PHP Data Objects` (PDO) 拡張モジュールは、 PHP の中からデータベースにアクセスするための軽量で高性能な インターフェイスを定義します。 PDO インターフェイスを実装する各データベースドライバは、 正規表現関数のようなデータベース固有の機能を提供することができます。 PDO 拡張モジュールによりそのデータベースの全てのデータベース関数を 実行できるわけではないことに注意してください。 データベースサーバーにアクセスするには、 データベース固有の PDO ドライバ を使用する必要があります。

PDO は、データアクセスの抽象化レイヤを提供します。 つまり、使用しているデータベースが何であるかにかかわらず、同じ 関数を使用してクエリの発行やデータの取得が行えるということです。 PDO は、データベースの抽象化を行うのでは ありません。つまり、SQL を書き直したり 存在しない機能をエミュレートしたりはしないということです。 もしそのような機能が必要なら、全体を網羅する (full-blown) 別の抽象化レイヤを使用すべきです。

PDO は PHP 本体にバンドルされています。

# インストール/設定

## 目次

- インストール手順
- 実行時設定

## インストール手順

この拡張モジュールはデフォルトで有効になっています。無効にしたい場合は、次のオプションを指定してコンパイルします。 --disable-pdo

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

1. PDO および PDO_SQLITE ドライバは、デフォルトで有効となっています。 必要に応じて、使用するデータベース用の PDO ドライバを有効にすることができます。 データベースごとの PDO ドライバについてのドキュメント を参照ください。

   > 注意:

   > PDO を共有モジュールとしてビルドする場合 (非推奨です)、 すべての PDO ドライバは PDO 自体の後に ロードしなければなりません。

2. PDO を共有モジュールとしてインストールする場合は、php.ini ファイルを変更し、PHP の実行時に PDO 拡張モジュールが自動的に読み込まれるようにしなければなりません。 データベースごとのドライバについても同様です。 ドライバは、extension=pdo ファイルの後に記述するようにしましょう。 ドライバを読み込む前に PDO の初期化を済ませておく必要があるからです。 PDO およびデータベースドライバを静的にビルドした場合は、この部分は読み飛ばしてかまいません。

       extension=pdo

Windows ユーザー

1. PDO はデフォルトで有効になっています。 php_pdo.dll をはじめに指定し、 さらにその他のデータベース固有の DLL について、実行時に dl() で読み込むか php.ini の中でそれらを指定します。 たとえば PDO_SQLITE ドライバを読み込み、PDO_ODBC をコメントアウトしたままにするには、以下のようにします:

       ;extension=pdo_odbc
       extension=pdo_sqlite

   これらの DLL は、システムの extension_dir になければなりません。

> 注意:

> php.ini ファイルを変更したら、 新しい設定を有効にするために PHP を再起動する必要があります。

## 実行時設定

php.ini の設定により動作が変化します。

PDO 設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
--- | --- | --- | ---
pdo.dsn.* |  | php.ini のみ |

以下に設定ディレクティブに関する 簡単な説明を示します。

`pdo.dsn.*` string

  DSN の別名を定義します。完全な説明については PDO::__construct() を参照ください。

# 定義済み定数

## 目次

- フェッチモード

以下の定数が定義されています。 この関数の拡張モジュールが PHP 組み込みでコンパイルされているか、 実行時に動的にロードされている場合のみ使用可能です。

## フェッチモード

`PDO::FETCH_ORI_*` カーソル定数については、 カーソル定数 を参照ください。

## 基本的なフェッチモード

フェッチモード | 概要
--- | ---
`PDO::FETCH_DEFAULT` | 現在のデフォルトフェッチモードを使用するための特別な値。
`PDO::FETCH_ASSOC` | カラム名のみでインデックス付けされた配列。
`PDO::FETCH_BOTH` (デフォルト) | カラム番号とカラム名の両方でインデックス付けされた配列。
`PDO::FETCH_NAMED` | 重複するカラムを保持する `PDO::FETCH_ASSOC` の変形。
`PDO::FETCH_NUM` | カラム番号のみでインデックス付けされた配列。
`PDO::FETCH_COLUMN` | 単一のカラム。
`PDO::FETCH_KEY_PAIR` | 最初のカラムでインデックス付けされたキーと値のペア。
`PDO::FETCH_FUNC` | 戻り値を生成するために関数を使用します。 (PDOStatement::fetchAll() のみ)
`PDO::FETCH_OBJ` | 無名の (stdClass) オブジェクト。
`PDO::FETCH_CLASS` | 指定されたクラスのオブジェクト。

## PDO::FETCH_CLASS のオプション

これらのモードは `PDO::FETCH_CLASS` 使用時のオプションを実装するために使用されます。

フェッチモード | 概要
--- | ---
`PDO::FETCH_CLASSTYPE` | 最初のカラムをクラス名として使用します。
`PDO::FETCH_PROPS_LATE` | プロパティを設定する前にコンストラクタを呼び出します。
`PDO::FETCH_SERIALIZE` | PHP のシリアライズされたデータを使用します。PHP 8.1.0 以降は推奨されません。

## 単一結果モード

以下のモードは PDOStatement::fetchAll() では使用できません。

フェッチモード | 概要
--- | ---
`PDO::FETCH_BOUND` | 指定した変数に値をバインドします。
`PDO::FETCH_INTO` | 既存のオブジェクトを更新します。
`PDO::FETCH_LAZY` | 配列風およびオブジェクト風のアクセスのための PDORow による遅延フェッチ。

## PDOStatement::fetchAll() 用の特殊な動作フラグ

以下の複数結果用の特殊モードは PDOStatement::fetchAll() でのみ動作し、 一部の他のフェッチモードとは組み合わせて使用できません。 詳細については完全なドキュメントを確認してください。

フェッチモード | 概要
--- | ---
`PDO::FETCH_GROUP` | 結果は最初のカラムでグループ化されます。
`PDO::FETCH_UNIQUE` | 結果は最初のカラムで (一意に) インデックス付けされます。

## 重複するカラム名の処理

結果に同じ名前のカラムが複数含まれる場合があります。 たとえば、同じカラム名を持つ 2 つのテーブルを結合する場合などです。

PHP の配列やオブジェクトなどの構造は、同じ名前の複数のキーや プロパティをサポートしていないため、返される配列やオブジェクトには 同じ名前を使用する値のうち 1 つだけが含まれます。

重複する名前に対してどの値が返されるかは未定義と考えるべきです。

この問題を回避するには、エイリアスを使用してカラムに明示的に名前を付けてください。 例:

    SELECT table1.created_at AS t1_created_at,
           table2.created_at AS t2_created_at
    FROM table1
    JOIN table2 ON table1.table2id = table2.id

`PDO::FETCH_NAMED`、 `PDO::ATTR_FETCH_TABLE_NAMES` および `PDO::ATTR_FETCH_CATALOG_NAMES` も参照ください。

## デフォルトのフェッチモードの設定

PDO::__construct() または PDO::setAttribute() で `PDO::ATTR_DEFAULT_FETCH_MODE` を使用して、すべてのクエリに対するデフォルトのフェッチモードを設定できます。

特定のステートメントに対するデフォルトのフェッチモードは、 PDOStatement::setFetchMode() を使用して設定できます。 これはプリペアドステートメントの再利用や (`foreach` を使用した) イテレーションに影響します。

警告

PDOStatement::setAttribute() はデフォルトのフェッチモードの 設定には使用できません。ドライバ固有の属性のみを受け入れ、 認識されない属性は警告なく無視されます。

## PDO::FETCH_DEFAULT (int)

PHP 8.0.7 以降で利用可能です。

これは PDOStatement に対する現在のデフォルトのフェッチモードを使用する特別な値です。 `PDO::ATTR_STATEMENT_CLASS` と共に使用するために PDOStatement を拡張する際のメソッドパラメータのデフォルト値として特に有用です。

この値は `PDO::ATTR_DEFAULT_FETCH_MODE` と共には使用できません。

## PDO::FETCH_ASSOC (int)

`PDO::FETCH_ASSOC` はカラム名のみでインデックス付けされた 配列を返します。

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users");
    $row = $stmt->fetch(\PDO::FETCH_ASSOC);
    print_r($row);

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

    Array
    (
        [userid] => 104
        [name] => Chris
        [country] => Ukraine
    )

## PDO::FETCH_BOTH (int)

これはデフォルトのフェッチモードです。

`PDO::FETCH_BOTH` はカラム番号とカラム名の両方で インデックス付けされた配列を返します。これは、結果行ごとに すべての返される値が重複することを意味します。

カラム番号は 0 から始まり、クエリ内の結果カラムの順序によって決まります。 テーブルでカラムが定義されている順序などではありません。

> 注意: 数値カラムインデックスの使用は推奨されません。 クエリが変更された場合や、`SELECT *` を使用している場合にテーブルスキーマが変更されると、 インデックスが変わる可能性があるためです。

> 注意: 複数の返されるカラムが同じ名前を使用する場合、 名前でインデックス付けされたエントリの数は 番号でインデックス付けされたエントリの数と一致しないことがあります。

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users");
    $row = $stmt->fetch(\PDO::FETCH_BOTH);
    print_r($row);

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

    Array
    (
        [id] => 104,
        [0] => 104,
        [name] => Chris,
        [1] => Chris,
        [country] => Ukraine,
        [2] => Ukraine
    )

## PDO::FETCH_NAMED (int)

`PDO::FETCH_NAMED` は `PDO::FETCH_ASSOC` と同じ形式で結果を返しますが、 複数のカラムが同じ名前を使用する場合、すべての値がリストとして返されます。

重複するカラム名の処理と代替方法についての詳細は、上記の 重複する名前の処理に関する セクション を参照ください。

重複した値が返される順序は未定義と考えるべきです。 各値がどこから来たのかを知る方法はありません。

    <?php
    $stmt = $pdo->query(
        "SELECT users.*, referrer.name
         FROM users
         LEFT JOIN users AS referrer ON users.referred_by = referrer.userid
         WHERE userid = 109"
    );
    $row = $stmt->fetch(\PDO::FETCH_NUM);
    print_r($row);

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

    Array
    (
        [userid] => 109
        [name] => Array
            (
                [0] => Toni
                [1] => Chris
            )
        [country] => Germany
        [referred_by] = 104
    )

## PDO::FETCH_NUM (int)

`PDO::FETCH_NUM` はカラム番号のみでインデックス付けされた 配列を返します。カラム番号は 0 から始まり、 クエリ内の結果カラムの順序によって決まります。 テーブルでカラムが定義されている順序などではありません。

> 注意: 数値カラムインデックスの使用は推奨されません。 クエリが変更された場合や、`SELECT *` を使用している場合にテーブルスキーマが変更されると、 インデックスが変わる可能性があるためです。

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users");
    $row = $stmt->fetch(\PDO::FETCH_NUM);
    print_r($row);

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

    Array
    (
        [0] => 104
        [1] => Chris
        [2] => Ukraine
    )

## PDO::FETCH_COLUMN (int)

`PDO::FETCH_COLUMN` は単一のカラムの値を返します。 PDOStatement::setFetchMode() または PDOStatement::fetchAll() の第二引数を使用して、どのカラムを返すかを指定します。

指定されたカラムが存在しない場合、 ValueError がスローされます。

    <?php
    $stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_COLUMN);
    print_r($row);

    $stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_COLUMN, 1);
    print_r($row);

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

    Array
    (
        [0] => Chris
        [1] => Jamie
        [2] => Robin
    )

    Array
    (
        [0] => Ukraine
        [1] => England
        [2] => Germany
    )

## PDO::FETCH_KEY_PAIR (int)

`PDO::FETCH_KEY_PAIR` は最初のカラムでインデックス付けされた 値のペアを返します。結果には 2 つのカラムのみが含まれている必要があります。 このフェッチモードは PDOStatement::fetchAll() でのみ意味があります。

> 注意: 最初のカラムが一意でない場合、値が失われます。 どの値が失われるかは未定義と考えるべきです。

    <?php
    $stmt = $pdo->query("SELECT name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_KEY_PAIR);
    print_r($row);

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

    Array
    (
        [Chris] => Ukraine
        [Jamie] => England
        [Robin] => Germany
    )

## PDO::FETCH_FUNC (int)

返される値を生成するための関数を指定します。このモードは PDOStatement::fetchAll() でのみ使用できます。

関数は値をパラメータとして受け取ります。 指定された値がどのカラム名に関連付けられているかを取得する方法はありません。 クエリ内のカラムの順序が関数のパラメータの順序と一致していることを 確認することが重要です。

> 注意: `PDO::FETCH_GROUP` および `PDO::FETCH_UNIQUE` の効果は、関数が呼び出される前に結果に適用されます。

    <?php
    function valueCreator($col1, $col2, $col3)
    {
        return [
            'col1' => $col1,
            'col2' => strtoupper($col2),
            'col3' => $col3,
            'customKey' => 'customValue',
        ];
    }

    $stmt = $pdo->query("SELECT userid, name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_FUNC, valueCreator(...));
    print_r($row);

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

    Array
    (
        [0] => Array
            (
                [col1] => 104
                [col2] => SAM
                [col3] => Ukraine
                [customKey] => customValue
            )

        [1] => Array
            (
                [col1] => 105
                [col2] => JAMIE
                [col3] => England
                [customKey] => customValue
            )

        [2] => Array
            (
                [col1] => 107
                [col2] => ROBIN
                [col3] => Germany
                [customKey] => customValue
            )

    )

## PDO::FETCH_OBJ (int)

`PDO::FETCH_OBJ` は stdClass オブジェクトを返します。

PDOStatement::fetchObject() および `PDO::FETCH_CLASS` も参照ください。

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users");
    $row = $stmt->fetch(\PDO::FETCH_OBJ);
    print_r($row);

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

    stdClass Object
    (
        [userid] => 104
        [name] => Chris
        [country] => Ukraine
    )

## PDO::FETCH_CLASS (int)

指定されたクラスのオブジェクトを返します。追加の動作については オプションフラグ を参照ください。

返されるカラム名と一致するプロパティが存在しない場合、 そのプロパティは動的に宣言されます。この動作は推奨されず、 PHP 9.0 からはエラーが発生します。

PDOStatement::fetchObject() も参照ください。

    <?php
    class TestEntity
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;

        public function __construct()
        {
            print "Constructor called with ". count(func_get_args()) ." args\n";
            print "Properties set when constructor called? "
                . (isset($this->name) ? 'Yes' : 'No') . "\n";
        }
    }

    $stmt = $db->query(
        "SELECT userid, name, country, referred_by_userid FROM users"
    );
    $stmt->setFetchMode(PDO::FETCH_CLASS, TestEntity::class);
    $result = $stmt->fetch();
    var_dump($result);

上の例の出力は、 たとえば以下のようになります。

    Constructor called with 0 args
    Properties set when constructor called? Yes
    object(TestEntity)#3 (4) {
      ["userid"]=>
      int(104)
      ["name"]=>
      string(5) "Chris"
      ["country"]=>
      string(7) "Ukraine"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_CLASSTYPE (int)

このフェッチモードは `PDO::FETCH_CLASS` (および その他のオプション) と組み合わせてのみ使用できます。

このフェッチモードが使用されると、PDO は返される最初のカラムを 返すクラスの名前として使用します。

指定されたクラスが見つからない場合、警告やエラーなしに stdClass オブジェクトが返されます。

    <?php
    class TestEntity
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;

        public function __construct()
        {
            print "Constructor called with ". count(func_get_args()) ." args\n";
            print "Properties set when constructor called? "
                . (isset($this->name) ? 'Yes' : 'No') . "\n";
        }
    }

    $stmt = $db->query(
        "SELECT 'TestEntity', userid, name, country, referred_by_userid FROM users"
    );
    $stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_CLASSTYPE);
    $result = $stmt->fetch();
    var_dump($result);

上の例の出力は、 たとえば以下のようになります。

    Constructor called with 0 args
    Properties set when constructor called? Yes
    object(TestEntity)#3 (4) {
      ["userid"]=>
      int(104)
      ["name"]=>
      string(5) "Chris"
      ["country"]=>
      string(7) "Ukraine"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_PROPS_LATE (int)

このフェッチモードは `PDO::FETCH_CLASS` (および その他のオプション) と組み合わせてのみ使用できます。

このフェッチモードが使用されると、プロパティが設定される前に コンストラクタが呼び出されます。

    <?php
    class TestEntity
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;

        public function __construct()
        {
            print "Constructor called with ". count(func_get_args()) ." args\n";
            print "Properties set when constructor called? "
                . (isset($this->name) ? 'Yes' : 'No') . "\n";
        }
    }

    $stmt = $db->query(
        "SELECT userid, name, country, referred_by_userid FROM users"
    );
    $stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_PROPS_LATE, TestEntity::class);
    $result = $stmt->fetch();
    var_dump($result);

上の例の出力は、 たとえば以下のようになります。

    Constructor called with 0 args
    Properties set when constructor called? No
    object(TestEntity)#3 (4) {
      ["userid"]=>
      int(104)
      ["name"]=>
      string(5) "Chris"
      ["country"]=>
      string(7) "Ukraine"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_SERIALIZE (int)

警告

この機能は PHP 8.1.0 で 非推奨になります。この機能に頼らないことを強く推奨します。

このフェッチモードは `PDO::FETCH_CLASS` (および その他のオプション) と組み合わせてのみ使用できます。

このフェッチモードが使用される場合、指定されたクラスは Serializable でなければなりません。

警告

この機能は (serialize() による) 完全なシリアライズされたオブジェクトを含む文字列をサポートしていません。

警告

このフェッチモードはコンストラクタを呼び出しません。

    <?php
    class TestEntity implements Serializable
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;

        public function __construct()
        {
            print "Constructor called with " . count(func_get_args()) . " args\n";
            print "Properties set when constructor called? "
                . (isset($this->name) ? 'Yes' : 'No') . "\n";
        }

        public function serialize()
        {
            return join(
                "|",
                [$this->userid, $this->name, $this->country, $this->referred_by_userid]
            );
        }

        public function unserialize(string $data)
        {
            $parts = explode("|", $data);
            $this->userid = (int) $parts[0];
            $this->name = $parts[1];
            $this->country = $parts[2];

            $refId = $parts[3];
            $this->referred_by_userid = ($refId === "" ? null : (int) $refId);
        }
    }

    print "Set up record (constructor called manually):\n";
    $db->exec(
        "CREATE TABLE serialize (
            sdata TEXT
        )"
    );

    $origObj = new TestEntity();
    $origObj->userid = 200;
    $origObj->name = 'Seri';
    $origObj->country = 'Syria';
    $origObj->referred_by_userid = null;

    $insert = $db->prepare("INSERT INTO serialize (sdata) VALUES (:sdata)");
    $insert->execute(['sdata' => $origObj->serialize()]);

    print "\nRetrieve result:\n";
    $query = "SELECT sdata FROM serialize";
    $stmt = $db->query($query);
    // 注意: コンストラクタは呼び出されません！
    $stmt->setFetchMode(PDO::FETCH_CLASS | PDO::FETCH_SERIALIZE, TestEntity::class);
    $result = $stmt->fetch();
    var_dump($result);

上の例の出力は、 たとえば以下のようになります。

    Deprecated: TestEntity implements the Serializable interface, which is deprecated. Implement __serialize() and __unserialize() instead (or in addition, if support for old PHP versions is necessary) in Standard input code on line 2
    Set up record (constructor called manually):
    Constructor called with 0 args
    Properties set when constructor called? No

    Retrieve result:
    Deprecated: PDOStatement::setFetchMode(): The PDO::FETCH_SERIALIZE mode is deprecated in Standard input code on line 58

    Deprecated: PDOStatement::fetch(): The PDO::FETCH_SERIALIZE mode is deprecated in Standard input code on line 59
    object(TestEntity)#5 (4) {
      ["userid"]=>
      int(200)
      ["name"]=>
      string(4) "Seri"
      ["country"]=>
      string(5) "Syria"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_BOUND (int)

このフェッチモードは PDOStatement::fetchAll() では使用できません。

このフェッチモードは結果を直接返すのではなく、 PDOStatement::bindColumn() で指定された変数に値をバインドします。 呼び出されたフェッチメソッドは `true` を返します。

> 注意: プリペアドステートメントを使用する場合、正しく動作させるには クエリが実行された後に変数をバインドする必要があります。

    <?php
    $query = "SELECT users.userid, users.name, users.country, referrer.name
        FROM users
        LEFT JOIN users AS referrer ON users.referred_by_userid = referrer.userid";
    $stmt = $db->prepare($query);
    $stmt->execute();

    $stmt->bindColumn('userid', $userId);
    $stmt->bindColumn('name', $name);
    $stmt->bindColumn('country', $country);
    // 重複するカラム名を解決するためにカラム位置でバインドする
    // クエリが変更された場合に壊れないようにするには、SQL エイリアスを使用してください
    // 例: referrer.name AS referrer_name
    $stmt->bindColumn(4, $referrerName);

    while ($stmt->fetch(\PDO::FETCH_BOUND)) {
        print join("\t", [$userId, $name, $country, ($referrerName ?? 'NULL')]) . "\n";
    }

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

    104	Chris	Ukraine	NULL
    105	Jamie	England	NULL
    107	Robin	Germany	Chris
    108	Sean	Ukraine	NULL
    109	Toni	Germany	NULL
    110	Toni	Germany	NULL

## PDO::FETCH_INTO (int)

このフェッチモードは PDOStatement::fetchAll() では使用できません。

このフェッチモードは指定されたオブジェクトのプロパティを更新します。 成功した場合、オブジェクトが返されます。

返されるカラム名と一致するプロパティが存在しない場合、 そのプロパティは動的に宣言されます。この動作は推奨されず、 PHP 9.0 からはエラーが発生します。

プロパティは `public` でなければならず、 `readonly` にはできません。

警告

各レコードの取得間で PDOStatement::setFetchMode() を使用せずに、更新対象のオブジェクトを変更する方法はありません。

    <?php

    class TestEntity
    {
        public $userid;

        public $name;

        public $country;

        public $referred_by_userid;
    }

    $obj = new TestEntity();

    $stmt = $db->query("SELECT userid, name, country, referred_by_userid FROM users");

    $stmt->setFetchMode(\PDO::FETCH_INTO, $obj);
    $result = $stmt->fetch();

    var_dump($result);

上の例の出力は、 たとえば以下のようになります。

    object(TestEntity)#3 (4) {
      ["userid"]=>
      int(104)
      ["name"]=>
      string(5) "Chris"
      ["country"]=>
      string(7) "Ukraine"
      ["referred_by_userid"]=>
      NULL
    }

## PDO::FETCH_LAZY (int)

このフェッチモードは PDOStatement::fetchAll() では使用できません。

このフェッチモードは PDORow オブジェクトを返し、 値への配列風およびオブジェクト風のアクセスを提供します (つまり、`PDO::FETCH_BOTH` と `PDO::FETCH_OBJ` の動作を組み合わせたもの)。 値は遅延的に取得されます。

これは、データベースサーバー上のバッファリングされていない結果への (PHP 側で) メモリ効率の良いアクセスを提供できます。 PDO が結果にクライアント側のバッファリングを使用するかどうかは、 使用されるデータベース固有のドライバ (およびその設定) に依存します。

警告

PDORow は、定義されていないプロパティやキーに アクセスした場合、エラーや警告なしに `NULL` を返します。 これにより、タイプミスや期待されるデータを返さないクエリなどのエラーを 発見してデバッグすることが難しくなる可能性があります。

警告

返される PDORow オブジェクトは、 結果が取得されるたびに更新されます。

    <?php
    $stmt = $db->query("SELECT userid, name, country, referred_by_userid FROM users");
    $result = $stmt->fetch(\PDO::FETCH_LAZY);

    print "ID: ". $result[0] ."\n";
    print "Name: {$result->name}\n";
    print "Country: " . $result['country'] ."\n";
    // NULL を返します。警告やエラーは発生しません。
    print "Does not exist: " . var_export($result->does_not_exist, true) . "\n";

    $differentResult = $stmt->fetch(\PDO::FETCH_LAZY);
    // 以前取得した PDORow は、新しく取得された結果を指すようになります
    print "ID: ". $result[0] ."\n";

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

    ID: 104
    Name: Chris
    Country: Ukraine
    Does not exist: NULL
    ID: 105

## PDO::FETCH_GROUP (int)

`PDO::FETCH_GROUP` は、(一意でない) カラムで インデックス付けされた連想配列のリストを返します。 このフェッチモードは PDOStatement::fetchAll() でのみ動作します。

`PDO::FETCH_UNIQUE` と組み合わせた場合、 両方のモードが同じカラムを使用するため、 これらのモードの組み合わせは無意味になります。

このフェッチは `PDO::FETCH_ASSOC`、`PDO::FETCH_BOTH`、 `PDO::FETCH_NAMED`、`PDO::FETCH_NUM`、 `PDO::FETCH_COLUMN` または `PDO::FETCH_FUNC` のいずれかと組み合わせる必要があります。

上記のリストのフェッチモードが指定されない場合、 PDOStatement の現在のデフォルトのフェッチモードが使用されます。

    <?php
    $stmt = $pdo->query("SELECT country, userid, name FROM users");
    $row = $stmt->fetchAll(\PDO::FETCH_GROUP | \PDO::FETCH_ASSOC);
    print_r($row);

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

    Array
    (
        [Ukraine] => Array
            (
                [0] => Array
                    (
                        [userid] => 104
                        [name] => Chris
                    )

                [1] => Array
                    (
                        [userid] => 108
                        [name] => Sean
                    )

            )
        [England] => Array
            (
                [0] => Array
                    (
                        [userid] => 105
                        [name] => Jamie
                    )

            )

        [Germany] => Array
            (
                [0] => Array
                    (
                        [userid] => 107
                        [name] => Robin
                    )

                [1] => Array
                    (
                        [userid] => 109
                        [name] => Toni
                    )
            )
    )

上記の例では、最初のカラムが各行の配列から省略され、 キーとしてのみ利用可能であることに注意してください。 次の例のようにカラムを繰り返すことで含めることができます:

    <?php
    $stmt = $pdo->query("SELECT country, userid, name, country FROM users");
    $row = $stmt->fetchAll(\PDO::FETCH_GROUP | \PDO::FETCH_ASSOC);
    print_r($row);

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

    Array
    (
        [Ukraine] => Array
            (
                [0] => Array
                    (
                        [userid] => 104
                        [name] => Chris
                        [country] => Ukraine
                    )

                [1] => Array
                    (
                        [userid] => 108
                        [name] => Sean
                        [country] => Ukraine
                    )

            )
        [England] => Array
            (
                [0] => Array
                    (
                        [userid] => 105
                        [name] => Jamie
                        [country] => England
                    )

            )

        [Germany] => Array
            (
                [0] => Array
                    (
                        [userid] => 107
                        [name] => Robin
                        [country] => Germany
                    )

                [1] => Array
                    (
                        [userid] => 109
                        [name] => Toni
                        [country] => Germany
                    )
            )
    )

## PDO::FETCH_UNIQUE (int)

`PDO::FETCH_UNIQUE` は最初のカラムを使用してレコードを インデックス付けし、インデックス値ごとに 1 レコードを返します。 このフェッチモードは PDOStatement::fetchAll() でのみ動作します。

`PDO::FETCH_GROUP` と組み合わせた場合、 両方のモードが同じカラムを使用するため、 これらのモードの組み合わせは無意味になります。

このフェッチは `PDO::FETCH_ASSOC`、`PDO::FETCH_BOTH`、 `PDO::FETCH_NAMED`、`PDO::FETCH_NUM`、 `PDO::FETCH_COLUMN` または `PDO::FETCH_FUNC` のいずれかと組み合わせる必要があります。

上記のリストのフェッチモードが指定されない場合、 PDOStatement の現在のデフォルトのフェッチモードが使用されます。

一意であることがわかっているカラム (レコード ID など) と共に使用すると、 このモードはその値でインデックス付けされた結果を素早く返す機能を提供します。

> 注意: 最初のカラムが一意でない場合、値が失われます。 どの値が失われるかは未定義と考えるべきです。

警告

レコードのフィルタリングは、可能な限り SQL で行うべきです。 データベースはインデックスを使用してこのプロセスを最適化し、 必要なレコードのみを返します。 必要以上のレコードをデータベースから取得すると、 大きな結果セットの場合にメモリ使用量とクエリ時間が大幅に増加する可能性があります。

    <?php
    $stmt = $pdo->query("SELECT userid, name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_UNIQUE | \PDO::FETCH_ASSOC);
    print_r($row);

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

    Array
    (
        [104] => Array
            (
                [name] => Chris
                [country] => Ukraine
            )

        [105] => Array
            (
                [name] => Jamie
                [country] => England
            )

        [107] => Array
            (
                [name] => Robin
                [country] => Germany
            )

    )

上記の例では、最初のカラムが各行の配列から省略され、 キーとしてのみ利用可能であることに注意してください。 次の例のようにカラムを繰り返すことで含めることができます:

    <?php
    $stmt = $pdo->query("SELECT userid, userid, name, country FROM users LIMIT 3");
    $row = $stmt->fetchAll(\PDO::FETCH_UNIQUE | \PDO::FETCH_ASSOC);
    print_r($row);

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

    Array
    (
        [104] => Array
            (
                [userid] => 104
                [name] => Chris
                [country] => Ukraine
            )

        [105] => Array
            (
                [userid] => 105
                [name] => Jamie
                [country] => England
            )

        [107] => Array
            (
                [userid] => 107
                [name] => Robin
                [country] => Germany
            )

    )

## カーソル

`PDO::ATTR_CURSOR_NAME` も参照ください。

`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 オブジェクトを生成します。 これはデフォルトのカーソルです。 なぜなら、処理が一番高速で、 PHP ではもっとも一般的なデータアクセスパターンだからです。
`PDO::CURSOR_SCROLL` (int)
  スクローラブルカーソルを有する PDOStatement オブジェクトを作成します。 結果セットから取得した行を制御するための `PDO::FETCH_ORI_*` 定数を指定してください。

## その他の定数

`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::ATTR_AUTOCOMMIT` (bool)
  この値が `false` の場合、PDO は接続がトランザクションを開始できるように オートコミットを無効にしようとします。 PHP 8.4.0 以降、この定数は bool として型付けされています。 それ以前は、int として型付けされていました。
`PDO::ATTR_PREFETCH` (int)
  独自アプリケーションにおける、 メモリ使用量に対する速度のバランスを調整するためのプリフェッチサイズを設定します。 全てのデータベースとドライバの組み合わせでプリフェッチサイズの設定をサポートしているわけではありません。 プリフェッチサイズを大きくするとパフォーマンスは向上しますが、 メモリ使用量は増加します。
`PDO::ATTR_TIMEOUT` (int)
  データベースとの通信に対するタイムアウト値を秒で設定します。
`PDO::ATTR_ERRMODE` (int)
  この属性についての詳細は、 エラー及びエラー処理 を参照ください。
`PDO::ATTR_SERVER_VERSION` (int)
  この属性は読み取り専用です。 PDO が接続している、データベースサーバーのバージョンに関する情報を返します。
`PDO::ATTR_CLIENT_VERSION` (int)
  この属性は読み取り専用です。 PDO ドライバが使っているクライアントライブラリのバージョンに関する情報を返します。
`PDO::ATTR_SERVER_INFO` (int)
  この属性は読み取り専用です。 PDO が接続している、データベースサーバーのメタ情報に関する情報を返します。
`PDO::ATTR_CONNECTION_STATUS` (int)
`PDO::ATTR_CASE` (int)
  `PDO::CASE_*` 定数で指定されたケースにカラム名を変更します。
`PDO::ATTR_CURSOR_NAME` (int)
  カーソルに使用する名前を取得または設定します。 スクローラブルなカーソルと、 位置を指定した更新を行う場合に最も有用です。
`PDO::ATTR_CURSOR` (int)
  カーソルのタイプを指定します。 PDO は現在、 `PDO::CURSOR_FWDONLY` と `PDO::CURSOR_SCROLL` をサポートしています。 スクローラブルなカーソルが必要ない限り、 `PDO::CURSOR_FWDONLY` のままにしてください。
`PDO::ATTR_DRIVER_NAME` (int)
  ドライバ名を返します。

  例1 `PDO::ATTR_DRIVER_NAME` を使う

      <?php
       if ($db->getAttribute(PDO::ATTR_DRIVER_NAME) == 'mysql') {
         echo "Running on mysql; doing something mysql specific here\n";
       }
       ?>

`PDO::ATTR_ORACLE_NULLS` (int)
  データをフェッチ時に、 空文字を SQL の NULL 値に変換します。
`PDO::ATTR_PERSISTENT` (int)
  新規接続を生成するよりもむしろ持続的接続を要求します。 この属性に関する詳細は、 接続、および接続の管理 を参照ください。
`PDO::ATTR_STATEMENT_CLASS` (int)
  ステートメントが返すクラス名を設定します。
`PDO::ATTR_FETCH_CATALOG_NAMES` (int)
  結果セット中の各カラム名にカタログ名を追加します。 カタログ名とカラム名は、小数点 (.) で区切られます。 この属性のサポートはドライバレベルで行われます。 つまり、お使いのドライバではサポートされていない可能性があります。
`PDO::ATTR_FETCH_TABLE_NAMES` (int)
  結果セット中の各カラム名に、 そのカラムを含むテーブル名を先頭に付加します。 テーブル名とカラム名は小数点(.)で区切られます。 この属性のサポートはドライバレベルで行われます。 つまり、お使いのドライバではサポートされていない可能性があります。
`PDO::ATTR_STRINGIFY_FETCHES` (int)
  全てのフェッチする値 (`null` を除く) を強制的に文字列として扱います。 `PDO::ATTR_ORACLE_NULLS` を `PDO::NULL_TO_STRING` に設定しない限り、 `null` は変更されません。
`PDO::ATTR_MAX_COLUMN_LEN` (int)
  カラム名の最大の長さを設定します。
`PDO::ATTR_DEFAULT_FETCH_MODE` (int)
`PDO::ATTR_EMULATE_PREPARES` (bool)
  プリペアドステートメントのエミュレーションを有効にするか無効にするかを指定します。 ドライバの中には、ネイティブのプリペアドステートメントをサポートしていないものや、 限定的にしかサポートしていないものがあります。`true` が設定された場合、 PDO は常にプリペアドステートメントをエミュレートします。`false` が設定された場合、 ドライバのネイティブなプリペアドステートメントを使用します。 PHP 8.4.0 以降、この定数は bool として型付けされています。 それ以前は、int として型付けされていました。
`PDO::ATTR_DEFAULT_STR_PARAM` (int)
  デフォルトの文字列のパラメータタイプを設定します。 `PDO::PARAM_STR_NATL` と `PDO::PARAM_STR_CHAR` のうち、 いずれかひとつを選べます。 PHP 7.2.0 以降で利用可能です。
`PDO::ERRMODE_SILENT` (int)
  エラー時にエラーもしくは例外を発生させません。 開発者の方は明示的にエラーをチェックするようにしてください。 PHP 8.0.0 より前のバージョンでは、これがデフォルトのモードでした。 この属性に関する詳細は、 エラー及びエラー処理 を参照ください。
`PDO::ERRMODE_WARNING` (int)
  エラーが発生した場合、 PHP の `E_WARNING` メッセージを発行します。 この属性に関する詳細は、 エラー及びエラー処理 を参照ください。
`PDO::ERRMODE_EXCEPTION` (int)
  エラーが発生した場合、 PDOException をスローします。 PHP 8.0.0 以降では、これがデフォルトのモードです。 この属性に関する詳細は、 エラー及びエラー処理 を参照ください。
`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::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 は、持続的接続のクリーンアップを一切行いません。 一時テーブル、ロック、トランザクション、その他の状態依存の変更が、 接続の以前の使用から残存し、予期せぬ問題を引き起こす可能性があります。 詳細については、 持続的データベース接続 を参照ください。

> 注意:

> 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 テーブルでトランザクションを使おうとした場合にこの現象が発生します。

警告

DDL文を使った場合の暗黙のコミット: データベースによっては、 `DROP TABLE` や `CREATE TABLE`, のような database definition language (DDL) がトランザクション中に実行された場合に、 自動で暗黙のうちに `COMMIT` を発行するものがあります。 これは、DDL 文より前に行われた、同じトランザクション中のあらうる変更が 自動でコミット さて、ロールバックできないことを意味します。

こうした振る舞いをするデータベースの例として、 `MySQL` と `Oracle` が挙げられます。

例1 暗黙のコミットの例

    <?php
    $pdo->beginTransaction();
    $pdo->exec("INSERT INTO users (name) VALUES ('Rasmus')");
    $pdo->exec("CREATE TABLE test (id INT PRIMARY KEY)"); // Implicit COMMIT occurs here
    $pdo->rollBack(); // This will NOT undo the INSERT/CREATE for MySQL or Oracle
    ?>

ベストプラクティス: このような振る舞いを強制してくるデータベースを使う場合は、トランザクション中で DDL を使うのを避けましょう。 必要な場合には、DDL の操作をトランザクションのロジックと分離しましょう。

スクリプトが終了したり接続が閉じられようとした際に、もし処理が 完了していないトランザクションがあれば PDO が自動的に ロールバックします。これは、スクリプトが予期せぬ状態で終了した場合に データの不整合が発生するのを避けるための安全装置です。もし 明示的にコミットしていなければ、おそらく何かおかしなことが 起こったのだろうと推測されます。そのため、データを守るために ロールバックが行われるのです。

警告

自動的にロールバックが行われるのは、トランザクションを PDO::beginTransaction() で開始した場合のみです。 トランザクションを開始するクエリを手動で発行した場合、 PDO はそれを知ることができません。そのため、何か問題が発生しても ロールバックすることはできないのです。

例2 トランザクション内で一括処理を行う

以下の例では、新しい従業員のデータを作成しているものとします。 この従業員には 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 function __construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
?array `$options` = `null`
)
public function beginTransaction(): bool
public function commit(): bool
public static function connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
?array `$options` = `null`
): static
public function errorCode(): ?string
public function errorInfo(): array
public function exec(string `$statement`): int|false
public function getAttribute(int `$attribute`): mixed
public static function getAvailableDrivers(): array
public function inTransaction(): bool
public function lastInsertId(?string `$name` = `null`): string|false
public function prepare(string `$query`, array `$options` = []): PDOStatement|false
public function query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function rollBack(): bool
public function setAttribute(int `$attribute`, mixed `$value`): bool
}

## 変更履歴

バージョン | 説明
--- | ---
8.4.0 | クラス定数が型付けされました。

# PDO::beginTransaction

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::beginTransaction — トランザクションを開始する

### 説明

public function 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::commit

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::commit — トランザクションをコミットする

### 説明

public function 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::connect

(PHP 8 >= 8.4.0)

PDO::connect — データベースに接続しドライバが対応する PDO サブクラスを返す

### 説明

public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
?array `$options` = `null`
): static

接続するデータベースに対応する PDO サブクラスが 存在する場合そのインスタンスを、 存在しない場合は汎用的な 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 サブクラスが 存在する場合そのインスタンス、 または汎用的な PDO インスタンスを返します。

### エラー / 例外

指定されたデータベースへの接続に失敗した場合、 `PDO::ATTR_ERRMODE` が設定されているかどうかに関わらず、 PDOException をスローします。

### 参考

- Pdo\Dblib
- Pdo\Firebird
- Pdo\Mysql
- Pdo\Odbc
- Pdo\Pgsql
- Pdo\Sqlite
- PDO::__construct() - データベースへの接続を表す PDO インスタンスを生成する

# PDO::__construct

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::__construct — データベースへの接続を表す PDO インスタンスを生成する

### 説明

public function 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::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);

    ?>

# PDO::errorCode

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::errorCode — データベースハンドラにおける直近の操作に関連する SQLSTATE を取得する

### 説明

public function 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::errorInfo

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::errorInfo — データベースハンドラにおける直近の操作に関連する拡張エラー情報を取得する

### 説明

public function 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() - 文ハンドラにおける直近の操作に関連する拡張エラー情報を取得する

# PDO::exec

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::exec — SQL ステートメントを実行し、作用した行数を返す

### 説明

public function 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::getAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDO::getAttribute — データベース接続の属性を取得する

### 説明

public function 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::getAvailableDrivers

# pdo_drivers

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.3)

PDO::getAvailableDrivers -- pdo_drivers — 利用可能な PDO ドライバの配列を返す

### 説明

public static function PDO::getAvailableDrivers(): array
function pdo_drivers(): array

この関数は、PDO::__construct() の `DSN` パラメータで利用可能な全ての有効な PDO ドライバを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

PDO::getAvailableDrivers() は PDO ドライバ名の配列を返します。 もしドライバが何も利用できない場合、空の配列を返します。

### 例

例1 PDO::getAvailableDrivers() の例

    <?php
    print_r(PDO::getAvailableDrivers());
    ?>

上の例の出力は、 たとえば以下のようになります。

    Array
    (
        [0] => mysql
        [1] => sqlite
    )

# PDO::inTransaction

(PHP 5 >= 5.3.3, Bundled pdo_pgsql, PHP 7, PHP 8)

PDO::inTransaction — トランザクション内かどうかを調べる

### 説明

public function PDO::inTransaction(): bool

ドライバ内で、現在トランザクションがアクティブになっているかどうかを調べます。 このメソッドが機能するのは、トランザクションをサポートしているデータベースドライバのみです。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

トランザクションが現在アクティブな場合に `true`、 そうでないときに `false` を返します。

# PDO::lastInsertId

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::lastInsertId — 最後に挿入された行の ID あるいはシーケンスの値を返す

### 説明

public function 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::prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PHP 8,PECL pdo >= 0.1.0)

PDO::prepare — 文を実行する準備を行い、文オブジェクトを返す

### 説明

public function 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() - プリペアドステートメントを実行する

# PDO::query

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDO::query — プレースホルダを指定せずに、SQL ステートメントを準備して実行する

### 説明

public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function 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::quote

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.1)

PDO::quote — クエリ用の文字列をクオートする

### 説明

public function 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::rollBack

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::rollBack — トランザクションをロールバックする

### 説明

public function 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::setAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDO::setAttribute — 属性を設定する

### 説明

public function 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`

  フェッチした値を(`null` を除いて)文字列に変換するかどうかを指定します。 bool の値を指定します: 変換を有効にする場合 `true`、 無効にする場合、`false` にします。 `PDO::ATTR_ORACLE_NULLS` を `PDO::NULL_TO_STRING` に設定しない限り、 `null` は変更されません。

`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() - 文の属性を設定する

## 目次

- PDO::beginTransaction — トランザクションを開始する
- PDO::commit — トランザクションをコミットする
- PDO::connect — データベースに接続しドライバが対応する PDO サブクラスを返す
- 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 クラス

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.0)

## はじめに

プリペアドステートメントを表します。ステートメント実行後は関連する結果セットを表します。

## クラス概要

class PDOStatement implements IteratorAggregate {
/* プロパティ */
public string $queryString;
/* メソッド */
public function bindColumn(
string|int `$column`,
mixed `&$var`,
int `$type` = `PDO::PARAM_STR`,
int `$maxLength` = 0,
mixed `$driverOptions` = `null`
): bool
public function bindParam(
string|int `$param`,
mixed `&$var`,
int `$type` = `PDO::PARAM_STR`,
int `$maxLength` = 0,
mixed `$driverOptions` = `null`
): bool
public function bindValue(string|int `$param`, mixed `$value`, int `$type` = `PDO::PARAM_STR`): bool
public function closeCursor(): bool
public function columnCount(): int
public function debugDumpParams(): ?bool
public function errorCode(): ?string
public function errorInfo(): array
public function execute(?array `$params` = `null`): bool
public function fetch(int `$mode` = `PDO::FETCH_DEFAULT`, int `$cursorOrientation` = `PDO::FETCH_ORI_NEXT`, int `$cursorOffset` = 0): mixed
public function fetchAll(int `$mode` = PDO::FETCH_DEFAULT): array
public function fetchAll(int `$mode` = PDO::FETCH_COLUMN, int `$column`): array
public function fetchAll(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs`): array
public function fetchAll(int `$mode` = PDO::FETCH_FUNC, callable `$callback`): array
public function fetchColumn(int `$column` = 0): mixed
public function fetchObject(?string `$class` = "stdClass", array `$constructorArgs` = []): object|false
public function getAttribute(int `$name`): mixed
public function getColumnMeta(int `$column`): array|false
public function getIterator(): Iterator
public function nextRowset(): bool
public function rowCount(): int
public function setAttribute(int `$attribute`, mixed `$value`): bool
public function setFetchMode(int `$mode`): true
public function setFetchMode(int `$mode` = PDO::FETCH_COLUMN, int `$colno`): true
public function setFetchMode(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs` = `null`): true
public function setFetchMode(int `$mode` = PDO::FETCH_INTO, object `$object`): true
}

## プロパティ

queryString

  使ったクエリ文字列。

## 変更履歴

バージョン | 説明
--- | ---
8.0.0 | PDOStatement は、 Traversable ではなく、 IteratorAggregate を実装するようになりました。

# PDOStatement::bindColumn

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::bindColumn — カラムを PHP 変数にバインドする

### 説明

public function 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::bindParam

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::bindParam — 指定された変数名にパラメータをバインドする

### 説明

public function 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::bindValue

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 1.0.0)

PDOStatement::bindValue — 値をパラメータにバインドする

### 説明

public function 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::closeCursor

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.9.0)

PDOStatement::closeCursor — カーソルを閉じてステートメントを再実行できるようにする

### 説明

public function 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::columnCount

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::columnCount — 結果セット中のカラム数を返す

### 説明

public function 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 ステートメントによって作用した行数を返す

# PDOStatement::debugDumpParams

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.9.0)

PDOStatement::debugDumpParams — SQL プリペアドコマンドを出力する

### 説明

public function 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() - 値をパラメータにバインドする

# PDOStatement::errorCode

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::errorCode — 文ハンドラにおける直近の操作に関連する SQLSTATE を取得する

### 説明

public function 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::errorInfo

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::errorInfo — 文ハンドラにおける直近の操作に関連する拡張エラー情報を取得する

### 説明

public function 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::execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::execute — プリペアドステートメントを実行する

### 説明

public function 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 = '?' . str_repeat(', ?', count($params) - 1);

    /*
        これは、配列 $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::fetch

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::fetch — 結果セットから次の行を取得する

### 説明

public function 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`: 要求されたクラスの新規インスタンスを返します。 結果セットのカラムをクラスのプロパティにマップしつつ、 オブジェクトは初期化されます。 この処理はコンストラクタをコールする前に行われるので、 プロパティのアクセス権に関係なく、たとえ `readonly` としてマークされていてもプロパティの値を集めることができます。 クラスにプロパティが存在しない場合は、マジックメソッド __set() が存在すればコールされます。 マジックメソッドが存在しない場合、public プロパティが動的に作成されます。 しかしながら、`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::fetchAll

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::fetchAll — 結果セットから、残っている行を取得する

### 説明

public function PDOStatement::fetchAll(int `$mode` = PDO::FETCH_DEFAULT): array
public function PDOStatement::fetchAll(int `$mode` = PDO::FETCH_COLUMN, int `$column`): array
public function PDOStatement::fetchAll(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs`): array
public function 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` パラメータにどのカラムを返すかを 指定することができます。

  配列のキーに(連続した数値ではなく)あるカラムの値を割り当てたい場合 SQL のカラムリスト中のカラム名を指定すると同時に `PDO::FETCH_UNIQUE` を指定します。 このカラムはユニークである必要があります。 そうしないと、データが失われます。

  指定したカラムの値によってグループ化した3次元配列を返す場合、 SQL のカラムリスト中のカラム名を指定すると同時に `PDO::FETCH_GROUP` を指定します。

  結果をグループ化した2次元配列で返す場合、 `PDO::FETCH_COLUMN` と一緒に `PDO::FETCH_GROUP` bit-OR で指定します。 この結果は、最初のカラムでグループ化され、 配列の要素の値はふたつめのカラムの対応するエントリの配列になります。

以下は `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::fetchColumn

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.9.0)

PDOStatement::fetchColumn — 結果セットの次行から単一カラムを返す

### 説明

public function 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::fetchObject

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.4)

PDOStatement::fetchObject — 次の行を取得し、それをオブジェクトとして返す

### 説明

public function 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::getAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::getAttribute — 文の属性を取得する

### 説明

public function PDOStatement::getAttribute(int `$name`): mixed

文の属性を取得します。現時点で共通の属性は存在しませんが、 ドライバ固有の属性のみ存在します。

- `PDO::ATTR_CURSOR_NAME` (Firebird と ODBC 固有): `UPDATE ... WHERE CURRENT OF` に対するカーソル名を取得する

ドライバ固有の属性は、 他のドライバでは使っては いけない ことに注意して下さい。

### パラメータ

`name`

  問い合わせる属性の名前。

### 戻り値

属性の値を返します。

### 参考

- PDO::getAttribute() - データベース接続の属性を取得する
- PDO::setAttribute() - 属性を設定する
- PDOStatement::setAttribute() - 文の属性を設定する

# PDOStatement::getColumnMeta

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::getColumnMeta — 結果セットのカラムに対するメタデータを返す

### 説明

public function 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::getIterator

(PHP 8)

PDOStatement::getIterator — 結果セットのイテレータを取得する

### 説明

public function PDOStatement::getIterator(): Iterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# PDOStatement::nextRowset

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::nextRowset — 複数の行セットを返す文ハンドラで次の行セットに移動する

### 説明

public function 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 ステートメントを準備して実行する

# PDOStatement::rowCount

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.1.0)

PDOStatement::rowCount — 直近の SQL ステートメントによって作用した行数を返す

### 説明

public function PDOStatement::rowCount(): int

PDOStatement::rowCount() は 相当する `PDOStatement` オブジェクトによって実行された 直近の DELETE, INSERT, UPDATE 文によって作用した行数を返します。

`SELECT`文のような、結果セットを生成するSQLステートメントについては動作が未定義です。 動作はドライバによって異なる可能性があります。 データベース(例: MySQL のバッファリングモード)によっては、文によって返された行数を返すかもしれません。しかしながら、 この振る舞いは全てのデータベースで保証されていません。 さまざまな場所で使用するアプリケーションでは、 これに頼ってはいけません。

> 注意:

> このメソッドは、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::setAttribute

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::setAttribute — 文の属性を設定する

### 説明

public function 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::setFetchMode

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo >= 0.2.0)

PDOStatement::setFetchMode — この文に対するデフォルトのフェッチモードを設定する

### 説明

public function PDOStatement::setFetchMode(int `$mode`): true
public function PDOStatement::setFetchMode(int `$mode` = PDO::FETCH_COLUMN, int `$colno`): true
public function PDOStatement::setFetchMode(int `$mode` = PDO::FETCH_CLASS, string `$class`, ?array `$constructorArgs` = `null`): true
public function PDOStatement::setFetchMode(int `$mode` = PDO::FETCH_INTO, object `$object`): true

### パラメータ

`mode`

  フェッチモードは、`PDO::FETCH_*` 定数の 1つでなければなりません。

`colno`

  カラム番号。

`class`

  クラス名。

`constructorArgs`

  コンストラクタの引数。

`object`

  オブジェクト。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 戻り値の型が、`true` になりました。これより前のバージョンでは、bool でした。

### 例

例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

## 目次

- 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 クラス

(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 string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* 継承したメソッド */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function 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 ドライバ
- Pdo\Dblib
- Firebird PDO ドライバ
- Pdo\Firebird
- IBM PDO ドライバ
- Informix PDO ドライバ
- MySQL PDO ドライバ
- Pdo\Mysql
- MS SQL Server PDO ドライバ
- Oracle PDO ドライバ
- ODBC and DB2 PDO ドライバ
- Pdo\Odbc
- PostgreSQL PDO ドライバ
- Pdo\Pgsql
- SQLite PDO ドライバ
- Pdo\Sqlite

以下のドライバが現在 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 ドライバ (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

(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_schema

(PECL PDO_CUBRID >= 8.3.0.0001)

PDO::cubrid_schema — 指定したスキーマ情報を取得する

### 説明

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

    )

## 目次

- PDO_CUBRID DSN — CUBRID データベースへの接続
- PDO::cubrid_schema — 指定したスキーマ情報を取得する

# Microsoft SQL Server および Sybase PDO ドライバ (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

(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

## 目次

- PDO_DBLIB DSN — Microsoft SQL Server および Sybase データベースに接続する

# Pdo\Dblib クラス

(PHP 8 >= 8.4.0)

## はじめに

DBLib PDO ドライバによる接続を示す PDO サブクラスです。

## クラス概要

namespace Pdo;
class Dblib extends PDO {
/* 継承した定数 */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* 定数 */
public const int ATTR_CONNECTION_TIMEOUT;
public const int ATTR_QUERY_TIMEOUT;
public const bool ATTR_STRINGIFY_UNIQUEIDENTIFIER;
public const int ATTR_VERSION;
public const int ATTR_TDS_VERSION;
public const int ATTR_SKIP_EMPTY_ROWSETS;
public const bool ATTR_DATETIME_CONVERT;
/* 継承したメソッド */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## 定義済み定数

`Pdo\Dblib::ATTR_CONNECTION_TIMEOUT`
`Pdo\Dblib::ATTR_QUERY_TIMEOUT`
`Pdo\Dblib::ATTR_STRINGIFY_UNIQUEIDENTIFIER`
  PHP 8.4.0 以降、この定数は bool として型付けされています。 それ以前は、int として型付けされていました。
`Pdo\Dblib::ATTR_VERSION`
`Pdo\Dblib::ATTR_TDS_VERSION`
`Pdo\Dblib::ATTR_SKIP_EMPTY_ROWSETS`
`Pdo\Dblib::ATTR_DATETIME_CONVERT`
  この接続属性は、datetime 型に対する文字列のフォーマットを制御します。 これが `false` の場合、PDO_DBLIB は datetime 型を、SQL Server が返すフォーマット （つまり `"2017-10-27 10:22:44"`）の文字列として返します。 `true` の場合、PDO_DBLIB は datetime 型を、FreeTDS の locales.conf ファイルで指定された、ユーザー定義の フォーマットあるいはロケールのフォーマットを使って文字列に変換します。 デフォルトでは、この属性は `false` です。 PHP 8.4.0 以降、この定数は bool として型付けされています。 それ以前は、int として型付けされていました。

# Firebird PDO ドライバ (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\Firebird::ATTR_DATE_FORMAT` のエイリアス

`PDO::FB_ATTR_TIME_FORMAT` (int)

  `Pdo\Firebird::ATTR_TIME_FORMAT` のエイリアス

`PDO::FB_ATTR_TIMESTAMP_FORMAT` (int)

  `Pdo\Firebird::ATTR_TIMESTAMP_FORMAT` のエイリアス

# 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=utf-8;dialect=1

## 目次

- PDO_FIREBIRD DSN — Firebird データベースに接続する

# Pdo\Firebird クラス

(PHP 8 >= 8.4.0)

## はじめに

Firebird PDO ドライバによる接続を示す PDO サブクラスです。

## クラス概要

namespace Pdo;
class Firebird extends PDO {
/* 継承した定数 */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* 定数 */
public const int ATTR_DATE_FORMAT;
public const int ATTR_TIME_FORMAT;
public const int ATTR_TIMESTAMP_FORMAT;
public const int TRANSACTION_ISOLATION_LEVEL;
public const int READ_COMMITTED;
public const int REPEATABLE_READ;
public const int SERIALIZABLE;
public const int WRITABLE_TRANSACTION;
/* メソッド */
public static function getApiVersion(): int
/* 継承したメソッド */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## 定義済み定数

`Pdo\Firebird::ATTR_DATE_FORMAT`
  日付フォーマットを設定します。
`Pdo\Firebird::ATTR_TIME_FORMAT`
  時刻フォーマットを設定します。
`Pdo\Firebird::ATTR_TIMESTAMP_FORMAT`
  タイムスタンプフォーマットを設定します。
`Pdo\Firebird::TRANSACTION_ISOLATION_LEVEL`
  トランザクション分離レベルを設定します。 `Pdo\Firebird::READ_COMMITTED`、 `Pdo\Firebird::REPEATABLE_READ`、 または `Pdo\Firebird::SERIALIZABLE` のいずれかです。
`Pdo\Firebird::READ_COMMITTED`
  ANSI トランザクション分離レベルが Read Committed であることを示すフラグです。 これがデフォルトの動作です。
`Pdo\Firebird::REPEATABLE_READ`
  ANSI トランザクション分離レベルが Repeatable Read であることを示すフラグです。 Firebird の "snapshot" 分離レベルに相当します。
`Pdo\Firebird::SERIALIZABLE`
  ANSI トランザクション分離レベルが Serializeable であることを示すフラグです。 Firebird の "snapshot table stability" 分離レベルに相当します。
`Pdo\Firebird::WRITABLE_TRANSACTION`
  ブール値で、トランザクションアクセスモードを `READ ONLY` または `READ WRITE` に設定します。 デフォルトは `true` で、`READ WRITE` を表します。

# Pdo\Firebird::getApiVersion

(PHP 8 >= 8.4.0)

Pdo\Firebird::getApiVersion — APIバージョンを取得する

### 説明

public static function Pdo\Firebird::getApiVersion(): int

ibase.h 内で C 言語の定数 `FB_API_VER` として定義されている Firebird API のバージョンを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

FireBird API のバージョンを int 型で返します。

## 目次

- Pdo\Firebird::getApiVersion — APIバージョンを取得する

# IBM PDO ドライバ (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

(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");

## 目次

- PDO_IBM DSN — IBM データベースへの接続

# Informix PDO ドライバ (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

(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");

## 目次

- PDO_INFORMIX DSN — Informix データベースに接続する

# MySQL PDO ドライバ (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::ATTR_SSL_*` を指定します。これは » 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` (int)
  `Pdo\Mysql::ATTR_USE_BUFFERED_QUERY` のエイリアス
`PDO::MYSQL_ATTR_LOCAL_INFILE` (int)
  `Pdo\Mysql::ATTR_LOCAL_INFILE` のエイリアス
`PDO::MYSQL_ATTR_LOCAL_INFILE_DIRECTORY` (int)
  `Pdo\Mysql::ATTR_LOCAL_INFILE_DIRECTORY` のエイリアス PHP 8.1.0 以降で利用可能です。
`PDO::MYSQL_ATTR_INIT_COMMAND` (int)
  `Pdo\Mysql::ATTR_INIT_COMMAND` のエイリアス
`PDO::MYSQL_ATTR_READ_DEFAULT_FILE` (int)
  `Pdo\Mysql::ATTR_READ_DEFAULT_FILE` のエイリアス
`PDO::MYSQL_ATTR_READ_DEFAULT_GROUP` (int)
  `Pdo\Mysql::ATTR_READ_DEFAULT_GROUP` のエイリアス
`PDO::MYSQL_ATTR_MAX_BUFFER_SIZE` (int)
  `Pdo\Mysql::ATTR_MAX_BUFFER_SIZE` のエイリアス
`PDO::MYSQL_ATTR_DIRECT_QUERY` (bool)
  `PDO::ATTR_EMULATE_PREPARES` のエイリアス PHP 8.4.0 以降、この定数は bool として型付けされています。 それ以前は、int として型付けされていました。
`PDO::MYSQL_ATTR_FOUND_ROWS` (int)
  `Pdo\Mysql::ATTR_FOUND_ROWS` のエイリアス
`PDO::MYSQL_ATTR_IGNORE_SPACE` (int)
  `Pdo\Mysql::ATTR_IGNORE_SPACE` のエイリアス
`PDO::MYSQL_ATTR_COMPRESS` (int)
  `Pdo\Mysql::ATTR_COMPRESS` のエイリアス
`PDO::MYSQL_ATTR_SERVER_PUBLIC_KEY` (int)
  `Pdo\Mysql::ATTR_SERVER_PUBLIC_KEY` のエイリアス
`PDO::MYSQL_ATTR_SSL_CA` (int)
  `Pdo\Mysql::ATTR_SSL_CA` のエイリアス
`PDO::MYSQL_ATTR_SSL_CAPATH` (int)
  `Pdo\Mysql::ATTR_SSL_CAPATH` のエイリアス
`PDO::MYSQL_ATTR_SSL_CERT` (int)
  `Pdo\Mysql::ATTR_SSL_CERT` のエイリアス
`PDO::MYSQL_ATTR_SSL_CIPHER` (int)
  `Pdo\Mysql::ATTR_SSL_CIPHER` のエイリアス
`PDO::MYSQL_ATTR_SSL_KEY` (int)
  `Pdo\Mysql::ATTR_SSL_KEY` のエイリアス
`PDO::MYSQL_ATTR_SSL_VERIFY_SERVER_CERT` (int)
  `Pdo\Mysql::ATTR_SSL_VERIFY_SERVER_CERT` のエイリアス PHP 7.0.18 および、PHP 7.1.4 以降で利用可能です。
`PDO::MYSQL_ATTR_MULTI_STATEMENTS` (int)
  `Pdo\Mysql::ATTR_MULTI_STATEMENTS` のエイリアス

## 実行時設定

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

(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 の設定を使って作られます。

## 目次

- PDO_MYSQL DSN — MySQL データベースに接続する

# Pdo\Mysql クラス

(PHP 8 >= 8.4.0)

## はじめに

MySQL PDO ドライバによる接続を示す PDO サブクラスです。

このドライバは MySQL 方言向けに専用の SQL クエリパーサーをサポートしています。 次のものを処理可能です:

- シングルクオートやダブルクオートで囲まれたリテラルでのクオートの二重化やバックスラッシュによるエスケープ
- バッククオートで囲まれたリテラルでのクオートの二重化によるエスケープ
- 2 つのハイフンによるコメント、C 言語形式のコメント、`#` によるコメント

## クラス概要

class Pdo\Mysql extends PDO {
/* 継承した定数 */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* 定数 */
public const int ATTR_USE_BUFFERED_QUERY;
public const int ATTR_LOCAL_INFILE;
public const int ATTR_LOCAL_INFILE_DIRECTORY;
public const int ATTR_INIT_COMMAND;
public const int ATTR_MAX_BUFFER_SIZE;
public const int ATTR_READ_DEFAULT_FILE;
public const int ATTR_READ_DEFAULT_GROUP;
public const int ATTR_COMPRESS;
public const int ATTR_DIRECT_QUERY;
public const int ATTR_FOUND_ROWS;
public const int ATTR_IGNORE_SPACE;
public const int ATTR_MULTI_STATEMENTS;
public const int ATTR_SERVER_PUBLIC_KEY;
public const int ATTR_SSL_KEY;
public const int ATTR_SSL_CERT;
public const int ATTR_SSL_CA;
public const int ATTR_SSL_CAPATH;
public const int ATTR_SSL_CIPHER;
public const int ATTR_SSL_VERIFY_SERVER_CERT;
/* メソッド */
public function getWarningCount(): int
/* 継承したメソッド */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## 定義済み定数

`Pdo\Mysql::ATTR_USE_BUFFERED_QUERY`
  デフォルトでは、全てのステートメントが バッファモード で実行されます。 この値を `false` に設定すると、 Pdo\Mysql オブジェクトの MySQL ドライバは非バッファモードを使います。

  例1 MySQL の非バッファモードを使う

      <?php
      $pdo = new Pdo\Mysql("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`
  `LOAD LOCAL INFILE` を有効にします。

  > 注意: この定数を使えるのは、新しいデータベースハンドルを作るときの `driver_options` 配列内に限ります。

`Pdo\Mysql::ATTR_LOCAL_INFILE_DIRECTORY`
  LOCAL DATA 文によるファイルのロードを、 ここで指定したディレクトリのみに制限します。

  > 注意: この定数を使えるのは、新しいデータベースハンドルを作るときの `driver_options` 配列内に限ります。

`Pdo\Mysql::ATTR_INIT_COMMAND`
  MySQL サーバーへの接続時に実行するコマンドを指定します。 再接続の際には自動的に再実行されます。

  > 注意: この定数を使えるのは、新しいデータベースハンドルを作るときの `driver_options` 配列内に限ります。

`Pdo\Mysql::ATTR_READ_DEFAULT_FILE`
  my.cnf ではなく、 指定した名前のファイルからオプションを読み込みます。

  > 注意: このオプションは、mysqlnd を使っている場合は利用できません。 mysqlnd は mysql の設定ファイルを読んでいないからです。

`Pdo\Mysql::ATTR_READ_DEFAULT_GROUP`
  my.cnf あるいは 別のファイル (`Pdo\Mysql::ATTR_READ_DEFAULT_FILE` で指定したもの) の中の、指定した名前のグループからオプションを読み込みます。

  > 注意: このオプションは、mysqlnd を使っている場合は利用できません。 mysqlnd は mysql の設定ファイルを読んでいないからです。

`Pdo\Mysql::ATTR_COMPRESS`
  ネットワーク通信の圧縮を有効にします。
`Pdo\Mysql::ATTR_DIRECT_QUERY`
  `PDO::ATTR_EMULATE_PREPARES` のエイリアス
`Pdo\Mysql::ATTR_FOUND_ROWS`
  変更された行数ではなく、 見つかった (マッチした) 行数を返します。

  > 注意: この定数を使えるのは、新しいデータベースハンドルを作るときの `driver_options` 配列内に限ります。

`Pdo\Mysql::ATTR_IGNORE_SPACE`
  関数名の後に続く空白を許可します。 すべての関数名が予約語になります。

  > 注意: この定数を使えるのは、新しいデータベースハンドルを作るときの `driver_options` 配列内に限ります。

`Pdo\Mysql::ATTR_MAX_BUFFER_SIZE`
  バッファの最大サイズ。デフォルトは 1 MiB です。

  > 注意: mysqlnd を指定してコンパイルした場合は、この定数はサポートされていません。

`Pdo\Mysql::ATTR_MULTI_STATEMENTS`
  `false` にすると、 PDO::prepare()や PDO::query() でのマルチクエリの実行を無効にします。

  > 注意: この定数を使えるのは、新しいデータベースハンドルを作るときの `driver_options` 配列内に限ります。

`Pdo\Mysql::ATTR_SERVER_PUBLIC_KEY`
  SHA-256 ベースの認証で使用する RSA 公開鍵ファイル。

  > 注意: この定数を使えるのは、新しいデータベースハンドルを作るときの `driver_options` 配列内に限ります。

`Pdo\Mysql::ATTR_SSL_KEY`
  SSL キーのファイルパス。

  > 注意: この定数を使えるのは、新しいデータベースハンドルを作るときの `driver_options` 配列内に限ります。

`Pdo\Mysql::ATTR_SSL_CERT`
  SSL 証明書のファイルパス。

  > 注意: この定数を使えるのは、新しいデータベースハンドルを作るときの `driver_options` 配列内に限ります。

`Pdo\Mysql::ATTR_SSL_CA`
  SSL 認証局のファイルパス。

  > 注意: この定数を使えるのは、新しいデータベースハンドルを作るときの `driver_options` 配列内に限ります。

`Pdo\Mysql::ATTR_SSL_CAPATH`
  信頼済みの SSL CA 証明書が入ったディレクトリパス。 証明書は、PEM フォーマットで格納されています。

  > 注意: この定数を使えるのは、新しいデータベースハンドルを作るときの `driver_options` 配列内に限ります。

`Pdo\Mysql::ATTR_SSL_CIPHER`
  SSL 暗号化に使うひとつ以上の暗号の一覧。 OpenSSL で有効なフォーマットで指定します。 例: `DHE-RSA-AES256-SHA:AES128-SHA`

  > 注意: この定数を使えるのは、新しいデータベースハンドルを作るときの `driver_options` 配列内に限ります。

`Pdo\Mysql::ATTR_SSL_VERIFY_SERVER_CERT`
  サーバーの SSL 証明書の検証を無効にする方法を提供します。

  > 注意: このオプションは、mysqlnd でのみ利用可能です。

  > 注意: この定数を使えるのは、新しいデータベースハンドルを作るときの `driver_options` 配列内に限ります。

# Pdo\Mysql::getWarningCount

(PHP 8 >= 8.4.0)

Pdo\Mysql::getWarningCount — 最後に実行したクエリの警告の数を返す

### 説明

public function Pdo\Mysql::getWarningCount(): int

最後に実行したクエリの警告の数を返します。

> 注意: 警告メッセージを取得するには、次の SQL コマンドを使用できます: `SHOW WARNINGS [limit row_count]`

### パラメータ

この関数にはパラメータはありません。

### 戻り値

最後に実行したクエリで発生した警告の数を int で返します。

### 例

例1 Pdo\Mysql::getWarningCount() の例

    <?php

    $conn = PDO::connect("mysql:host=localhost;dbname=test;charset=utf8mb4", 'user', 'password');

    $conn->query('SELECT 42/0');
    if ($conn->getWarningCount() > 0) {
        $result = $conn->query("SHOW WARNINGS");
        $row = $result->fetch();
        printf("%s (%d): %s\n", $row[0], $row[1], $row[2]);
    }

    ?>

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

    Warning (1365): Division by 0

## 目次

- Pdo\Mysql::getWarningCount — 最後に実行したクエリの警告の数を返す

# Microsoft SQL Server PDO ドライバ (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

(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");

## 目次

- PDO_SQLSRV DSN — MS SQL Server および SQL Azure データベースに接続する

# Oracle PDO ドライバ (PDO_OCI)

## インストール手順

Oracle データベースがPHPと同じマシンにインストールされている場合、 必要なライブラリはデータベースソフトウェアに既に含まれています。 PHP が Oracle データベースと違うマシンにある場合、 フリーの » Oracle インスタントクライアント ライブラリを使ってください。 詳細は OCI8 のインストール要件 のセクションを参照ください。

## PHP 8.4

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 8.4.0

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/PDO_OCI.

## PHP < 8.4

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

  データベースセッション上で、アクションを指定する方法を提供します。

  これが使えるようになった PHP のバージョンは 7.2.16 と 7.3.3 です。

`PDO::OCI_ATTR_CLIENT_INFO` (int)

  データベースセッション上で、クライアント情報を指定する方法を提供します。

  これが使えるようになった PHP のバージョンは 7.2.16 と 7.3.3 です。

`PDO::OCI_ATTR_CLIENT_IDENTIFIER` (int)

  データベースセッション上で、クライアント識別子を指定する方法を提供します。

  これが使えるようになった PHP のバージョンは 7.2.16 と 7.3.3 です。

`PDO::OCI_ATTR_MODULE` (int)

  データベースセッション上で、モジュールを指定する方法を提供します。

  これが使えるようになった PHP のバージョンは 7.2.16 と 7.3.3 です。

# 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

## 目次

- PDO_OCI DSN — Oracle データベースに接続する

# ODBC and DB2 PDO ドライバ (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)
  `Pdo\Odbc::ATTR_USE_CURSOR_LIBRARY` のエイリアス
`PDO::ODBC_SQL_USE_IF_NEEDED` (int)
  `Pdo\Odbc::SQL_USE_IF_NEEDED` のエイリアス
`PDO::ODBC_SQL_USE_DRIVER` (int)
  `Pdo\Odbc::SQL_USE_DRIVER` のエイリアス
`PDO::ODBC_SQL_USE_ODBC` (int)
  `Pdo\Odbc::SQL_USE_ODBC` のエイリアス
`PDO::ODBC_ATTR_ASSUME_UTF8` (bool)
  `Pdo\Odbc::ATTR_ASSUME_UTF8` のエイリアス

## 実行時設定

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

(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 はコンストラクタの引数で指定された パスワードを無視します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | PDO のコンストラクタに対してパスワード引数に空文字列を渡した場合、 今までは作成される接続文字列に `pwd` は含まれませんでした。このバージョンから、`pwd` は空文字列として含まれるように挙動が変更されました。 PDO のコンストラクタのパスワード引数に `null` を渡した場合の挙動は、 以前と同じです。
8.4.0 | DSN に `uid` または `pwd` が含まれている際には、 PDO のコンストラクタに name 引数と password 引数を別々に渡した場合に、 それらが無視されるように挙動が変更されました。 これより前のバージョンでは、 DSN に `uid` または `pwd` が含まれている場合にだけ、 PDO のコンストラクタに name 引数と password 引数を両方渡した場合に、 それらが無視されていました。

### 例

例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

## 目次

- PDO_ODBC DSN — ODBC あるいは DB2 データベースに接続する

# Pdo\Odbc クラス

(PHP 8 >= 8.4.0)

## はじめに

ODBC PDO ドライバによる接続を示す PDO サブクラスです。

## クラス概要

namespace Pdo;
class Odbc extends PDO {
/* 継承した定数 */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* 定数 */
public const int ATTR_USE_CURSOR_LIBRARY;
public const int ATTR_ASSUME_UTF8;
public const int SQL_USE_IF_NEEDED;
public const int SQL_USE_DRIVER;
public const int SQL_USE_ODBC;
/* 継承したメソッド */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## 定義済み定数

`Pdo\Odbc::ATTR_USE_CURSOR_LIBRARY`

  このオプションは、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`
  Windows のみ有効です。 `true` の場合、UTF-16 でエンコードされた文字データ(`CHAR`, `VARCHAR`, `LONGVARCHAR`) を データベースから読み取ったり、書き込んだりする際に UTF-8 に変換します。 `false` の場合(デフォルト)、エンコーディングの変換はドライバが行う可能性があります。

# PostgreSQL PDO ドライバ (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)
  `Pdo\Pgsql::ATTR_DISABLE_PREPARES` のエイリアス

## General notes

> 注意:

> `bytea` フィールドはストリームとして返されます。

# 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

# PDO::pgsqlCopyFromArray

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyFromArray — Pdo\Pgsql::copyFromArray() のエイリアス

### 説明

public function PDO::pgsqlCopyFromArray(
string `$tableName`,
array `$rows`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

このメソッドは次のメソッドのエイリアスです。 Pdo\Pgsql::copyFromArray().

# PDO::pgsqlCopyFromFile

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyFromFile — Pdo\Pgsql::copyFromFile() のエイリアス

### 説明

public function PDO::pgsqlCopyFromFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

このメソッドは次のメソッドのエイリアスです。 Pdo\Pgsql::copyFromFile().

# PDO::pgsqlCopyToArray

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyToArray — Pdo\Pgsql::copyToArray() のエイリアス

### 説明

public function PDO::pgsqlCopyToArray(
string `$tableName`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): array|false

このメソッドは次のメソッドのエイリアスです。 Pdo\Pgsql::copyToArray().

# PDO::pgsqlCopyToFile

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

PDO::pgsqlCopyToFile — Pdo\Pgsql::copyToFile() のエイリアス

### 説明

public function PDO::pgsqlCopyToFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

このメソッドは次のメソッドのエイリアスです。 Pdo\Pgsql::copyToFile().

# PDO::pgsqlGetNotify

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

PDO::pgsqlGetNotify — Pdo\Pgsql::getNotify() のエイリアス

### 説明

public function PDO::pgsqlGetNotify(int `$fetchMode` = PDO::FETCH_DEFAULT, int `$timeoutMilliseconds` = 0): array|false

このメソッドは次のメソッドのエイリアスです。 Pdo\Pgsql::getNotify().

# PDO::pgsqlGetPid

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

PDO::pgsqlGetPid — Pdo\Pgsql::getPid() のエイリアス

### 説明

public function PDO::pgsqlGetPid(): int

このメソッドは次のメソッドのエイリアスです。 Pdo\Pgsql::getPid().

# PDO::pgsqlLOBCreate

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBCreate — Pdo\Pgsql::lobCreate() のエイリアス

### 説明

public function PDO::pgsqlLOBCreate(): string

このメソッドは次のメソッドのエイリアスです。 Pdo\Pgsql::lobCreate().

# PDO::pgsqlLOBOpen

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBOpen — Pdo\Pgsql::lobOpen() のエイリアス

### 説明

public function PDO::pgsqlLOBOpen(string `$oid`, string `$mode` = "rb"): resource|false

このメソッドは次のメソッドのエイリアスです。 Pdo\Pgsql::lobOpen().

# PDO::pgsqlLOBUnlink

(PHP 5 >= 5.1.2, PHP 7, PHP 8, PECL pdo_pgsql >= 1.0.2)

PDO::pgsqlLOBUnlink — Pdo\Pgsql::lobUnlink() のエイリアス

### 説明

public function PDO::pgsqlLOBUnlink(string `$oid`): bool

このメソッドは次のメソッドのエイリアスです。 Pdo\Pgsql::lobUnlink().

## 目次

- PDO_PGSQL DSN — PostgreSQL データベースに接続する
- PDO::pgsqlCopyFromArray — Pdo\Pgsql::copyFromArray のエイリアス
- PDO::pgsqlCopyFromFile — Pdo\Pgsql::copyFromFile のエイリアス
- PDO::pgsqlCopyToArray — Pdo\Pgsql::copyToArray のエイリアス
- PDO::pgsqlCopyToFile — Pdo\Pgsql::copyToFile のエイリアス
- PDO::pgsqlGetNotify — Pdo\Pgsql::getNotify のエイリアス
- PDO::pgsqlGetPid — Pdo\Pgsql::getPid のエイリアス
- PDO::pgsqlLOBCreate — Pdo\Pgsql::lobCreate のエイリアス
- PDO::pgsqlLOBOpen — Pdo\Pgsql::lobOpen のエイリアス
- PDO::pgsqlLOBUnlink — Pdo\Pgsql::lobUnlink のエイリアス

# Pdo\Pgsql クラス

(PHP 8 >= 8.4.0)

## はじめに

PostgreSQL PDO ドライバによる接続を示す PDO サブクラスです。

このドライバは PostgreSQL 方言向けに専用の SQL クエリパーサーをサポートしています。 次のものを処理可能です:

- シングルクオートやダブルクオートで囲まれたリテラルでのクオートの二重化によるエスケープ
- C 言語形式の「エスケープ」文字列リテラル
- ドル記号で囲まれた文字列リテラル
- 2 つのハイフンによるコメント、ネストされていない C 言語形式のコメント
- `?` 演算子のエスケープシーケンスとしての `??` のサポート

## クラス概要

namespace Pdo;
class Pgsql extends PDO {
/* 継承した定数 */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* 定数 */
public const int ATTR_DISABLE_PREPARES;
public const int ATTR_RESULT_MEMORY_SIZE;
public const int TRANSACTION_IDLE;
public const int TRANSACTION_ACTIVE;
public const int TRANSACTION_INTRANS;
public const int TRANSACTION_INERROR;
public const int TRANSACTION_UNKNOWN;
/* メソッド */
public function copyFromArray(
string `$tableName`,
array `$rows`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool
public function copyFromFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool
public function copyToArray(
string `$tableName`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): array|false
public function copyToFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool
public function escapeIdentifier(string `$input`): string
public function getNotify(int `$fetchMode` = `PDO::FETCH_DEFAULT`, int `$timeoutMilliseconds` = 0): array|false
public function getPid(): int
public function lobCreate(): string|false
public function lobOpen(string `$oid`, string `$mode` = "rb"): resource|false
public function lobUnlink(string `$oid`): bool
public function setNoticeCallback(?callable `$callback`): void
/* 継承したメソッド */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## 定義済み定数

`Pdo\Pgsql::ATTR_DISABLE_PREPARES`
  SQL文とパラメータを一緒に、一回のコールでサーバーに送信します。 これによって、名前付きのプリペアドステートメントを別々に作ることを避けられます。 SQL文が一度しか実行されない場合、 不要なサーバーとの通信を避けられるので、レイテンシを抑えることができます。
`Pdo\Pgsql::ATTR_RESULT_MEMORY_SIZE`
  指定されたクエリ結果 PDOStatement インスタンスに割り当てられたメモリ使用量をバイト単位で返します。 クエリ実行前で結果が存在しない場合は `null` を返します。
`Pdo\Pgsql::TRANSACTION_IDLE`
`Pdo\Pgsql::TRANSACTION_ACTIVE`
`Pdo\Pgsql::TRANSACTION_INTRANS`
`Pdo\Pgsql::TRANSACTION_INERROR`
`Pdo\Pgsql::TRANSACTION_UNKNOWN`

# Pdo\Pgsql::copyFromArray

(PHP 8 >= 8.4.0)

Pdo\Pgsql::copyFromArray — PHP の配列から、データをテーブルにコピーする

### 説明

public function Pdo\Pgsql::copyFromArray(
string `$tableName`,
array `$rows`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

`rows` 配列からデータをテーブル `tableName` にコピーします。その際、`separator` を フィールドのデリミタ、そして `fields` のリストを使います。

### パラメータ

`tableName`
  テーブル名を含む文字列
`rows`
  `separator` で区切られたフィールドの文字列の配列
`separator`
  `rows` 配列の各要素の中で フィールドを分割するためのデリミタ
`nullAs`
  SQLの `NULL` 値をどのように扱うかを指定します
`fields`
  挿入するフィールドの一覧

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- Pdo\Pgsql::copyToArray() - データベーステーブルからのデータをPHPの配列にコピーする
- Pdo\Pgsql::copyFromFile() - ファイルからデータをテーブルにコピーする
- Pdo\Pgsql::copyToFile() - テーブルのデータをファイルにコピーする

# Pdo\Pgsql::copyFromFile

(PHP 8 >= 8.4.0)

Pdo\Pgsql::copyFromFile — ファイルからデータをテーブルにコピーする

### 説明

public function Pdo\Pgsql::copyFromFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

`filename` で指定されたファイルからデータを テーブル `tableName` にコピーします。その際、 `separator` をフィールドのデリミタ、そして `fields` のリストを使います。

### パラメータ

`tableName`
  テーブル名を含む文字列
`filename`
  インポートするデータを含むファイル名
`separator`
  `rows` 配列の各要素の中で フィールドを分割するためのデリミタ
`nullAs`
  SQLの `NULL` 値をどのように扱うかを指定します
`fields`
  挿入するフィールドの一覧

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- Pdo\Pgsql::copyToFile() - テーブルのデータをファイルにコピーする
- Pdo\Pgsql::copyFromArray() - PHP の配列から、データをテーブルにコピーする
- Pdo\Pgsql::copyToArray() - データベーステーブルからのデータをPHPの配列にコピーする

# Pdo\Pgsql::copyToArray

(PHP 8 >= 8.4.0)

Pdo\Pgsql::copyToArray — データベーステーブルからのデータをPHPの配列にコピーする

### 説明

public function Pdo\Pgsql::copyToArray(
string `$tableName`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): array|false

`tableName` のデータを配列にコピーします。その際、`separator` をフィールドのデリミタ、そして `fields` のリストを使います。

### パラメータ

`tableName`
  テーブル名を含む文字列
`separator`
  `rows` 配列の各要素の中で フィールドを分割するためのデリミタ
`nullAs`
  SQLの `NULL` 値をどのように扱うかを指定します
`fields`
  エクスポートするフィールドの一覧

### 戻り値

行の配列を返します。失敗した場合に `false` を返します

### 参考

- Pdo\Pgsql::copyFromArray() - PHP の配列から、データをテーブルにコピーする
- Pdo\Pgsql::copyFromFile() - ファイルからデータをテーブルにコピーする
- Pdo\Pgsql::copyToFile() - テーブルのデータをファイルにコピーする

# Pdo\Pgsql::copyToFile

(PHP 8 >= 8.4.0)

Pdo\Pgsql::copyToFile — テーブルのデータをファイルにコピーする

### 説明

public function Pdo\Pgsql::copyToFile(
string `$tableName`,
string `$filename`,
string `$separator` = "\t",
string `$nullAs` = "\\\\N",
?string `$fields` = `null`
): bool

`filename` で指定されたファイルに、テーブルからデータをコピーします。 その際、`separator` をフィールドのデリミタ、そして `fields` のリストを使います。

### パラメータ

`tableName`
  テーブル名を含む文字列
`filename`
  エキスポートするファイル名
`separator`
  `rows` 配列の各要素の中で フィールドを分割するためのデリミタ
`nullAs`
  SQLの `NULL` 値をどのように扱うかを指定します
`fields`
  挿入するフィールドの一覧

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- Pdo\Pgsql::copyFromFile() - ファイルからデータをテーブルにコピーする
- Pdo\Pgsql::copyFromArray() - PHP の配列から、データをテーブルにコピーする
- Pdo\Pgsql::copyToArray() - データベーステーブルからのデータをPHPの配列にコピーする

# Pdo\Pgsql::escapeIdentifier

(PHP 8 >= 8.4.0)

Pdo\Pgsql::escapeIdentifier — SQL識別子として使用するために文字列をエスケープする

### 説明

public function Pdo\Pgsql::escapeIdentifier(string `$input`): string

テーブル名、カラム名、または関数名など、SQL の識別子として使用する文字列をエスケープします。 これは、ユーザーから提供された識別子が特殊文字を含むため、 SQLパーサーが識別子の一部として解釈できない場合や、 大文字を含む識別子でそれを保持したい場合に有用です。

### パラメータ

`input`
  エスケープ対象の文字列(string)

### 戻り値

エスケープされた文字列(string) を返します。

### 例

例1 Pdo\Pgsql::escapeIdentifier() の例

    <?php
    $pdo = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);

    $unescapedTableName = 'UnescapedTableName';
    $pdo->exec("CREATE TABLE $unescapedTableName ()");

    $escapedTableName = $pdo->escapeIdentifier('EscapedTableName');
    $pdo->exec("CREATE TABLE $escapedTableName ()");

    $statement = $pdo->query(
      "SELECT relname FROM pg_stat_user_tables WHERE relname ilike '%tablename'"
    );

    var_export($statement->fetchAll(PDO::FETCH_COLUMN, 0));

    $tableNameWithSymbols = 'Table-Name-With-Symbols';
    $pdo->exec("CREATE TABLE $tableNameWithSymbols ()");
    ?>

上の例の出力は、 たとえば以下のようになります。

    array (
      0 => 'unescapedtablename',
      1 => 'EscapedTableName',
    )
    Fatal error: Uncaught PDOException: SQLSTATE[42601]: Syntax error: 7 ERROR:  syntax error at or near "Table"
    LINE 1: CREATE TABLE Table-Name-With-Symbols ()

### 参考

- PDO::quote() - クエリ用の文字列をクオートする

# Pdo\Pgsql::getNotify

(PHP 8 >= 8.4.0)

Pdo\Pgsql::getNotify — 非同期に通知を取得する

### 説明

public function Pdo\Pgsql::getNotify(int `$fetchMode` = `PDO::FETCH_DEFAULT`, int `$timeoutMilliseconds` = 0): array|false

保留中の非同期な通知を示す結果セットを返します。

### パラメータ

`fetchMode`

  結果セットを返すフォーマット。 次のいずれかの定数:

  - `PDO::FETCH_DEFAULT`
  - `PDO::FETCH_BOTH`
  - `PDO::FETCH_ASSOC`
  - `PDO::FETCH_NUM`
`timeoutMilliseconds`
  レスポンスを待つ時間の長さ。ミリ秒で指定します。

### 戻り値

ひとつ以上の通知が保留中だった場合、 `message` と `pid` のフィールドを含む1行を返します。 そうでなければ `false` を返します。

### エラー / 例外

`fetchMode` が有効な `PDO::FETCH_*` 定数のいずれでもない場合、ValueError がスローされます。

`timeoutMilliseconds` が`0` 未満の場合、 ValueError がスローされます。

`timeoutMilliseconds` が符号付き32ビットの整数に 収まらない場合、`E_WARNING` が発生し、 その値は符号付き32ビットの整数の最大値に丸められます。

### 参考

- PDO::query() - プレースホルダを指定せずに、SQL ステートメントを準備して実行する
- PDOStatement::fetch() - 結果セットから次の行を取得する
- PDOStatement::fetchAll() - 結果セットから、残っている行を取得する

# Pdo\Pgsql::getPid

(PHP 8 >= 8.4.0)

Pdo\Pgsql::getPid — 接続を処理するバックエンドプロセスのPIDを取得する

### 説明

public function Pdo\Pgsql::getPid(): int

この接続を処理するバックエンドプロセスのPIDを返します。 このPIDはローカルホストではなく、データベースサーバーが稼働するホスト上のプロセスを示す点に 注意してください。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

サーバーのPIDを int として返します。

# Pdo\Pgsql::lobCreate

(PHP 8 >= 8.4.0)

Pdo\Pgsql::lobCreate — 新しいラージオブジェクトを作成する

### 説明

public function Pdo\Pgsql::lobCreate(): string|false

Pdo\Pgsql::lobCreate() は、 ラージオブジェクトを作成してその OID を返します。 このオブジェクトに対するデータの読み書きは、 Pdo\Pgsql::lobOpen() を使用します。

OID は OID 型のカラムに格納され、 ラージオブジェクトを参照するために使用されます。 これにより、行のサイズがどんどん拡大してしまうことを防ぎます。 ラージオブジェクトは Pdo\Pgsql::lobUnlink() を コールして削除するまで、データベースに残り続けます。

ラージオブジェクトの取り扱いは複雑です。 オブジェクトの OID を参照している行をデータベースから削除する際には、 必ず事前に PDO::pgsqlLOBUnlink()をコールしなければなりません。 そうしないと、どこからも参照されないラージオブジェクトが、サーバーに残り続けてしまうでしょう。 さらに、ラージオブジェクトにはアクセス権を設定できません。 代替として、bytea 型のカラムも検討ください。最近のバージョンの PostgreSQL では bytea 型のカラムに最大 1GBまで保存でき、行サイズを最適化したうえでデータを透過的に扱うことができます。

> 注意: この関数を含むラージオブジェクトへの全ての操作は トランザクション内で行わなければなりません。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合、新しく作成されたラージオブジェクトの OID、 失敗した場合に `false` を返します。

### 例

例1 Pdo\Pgsql::lobCreate() の例

この例では、新しいラージオブジェクトを作成し、 ファイルの内容をそこにコピーします。その後、 OID がテーブルに保存されます。

    <?php
    $db = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);
    $db->setAttribute(PDO::ATTR_ERRMODE, PDO::ERRMODE_EXCEPTION);
    $db->beginTransaction();
    $oid = $db->lobCreate();
    $stream = $db->lobOpen($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([$some_id, $oid]);
    $db->commit();
    ?>

### 参考

- Pdo\Pgsql::lobOpen() - 既存のラージオブジェクトのストリームをオープンする
- Pdo\Pgsql::lobUnlink() - ラージオブジェクトを削除する
- pg_lo_create() - ラージオブジェクトを生成する
- pg_lo_open() - ラージオブジェクトをオープンする

# Pdo\Pgsql::lobOpen

(PHP 8 >= 8.4.0)

Pdo\Pgsql::lobOpen — 既存のラージオブジェクトのストリームをオープンする

### 説明

public function Pdo\Pgsql::lobOpen(string `$oid`, string `$mode` = "rb"): resource|false

Pdo\Pgsql::lobOpen() は、`oid` が指すデータにアクセスするためのストリームをオープンします。 fread()、fwrite() および fgets() などの通常のファイルシステム関数を使用して、 ストリームの内容を操作することができます。

> 注意: この関数を含むラージオブジェクトへの全ての操作は トランザクション内で行わなければなりません。

### パラメータ

`oid`
  ラージオブジェクトの ID。
`mode`
  モードが `r` の場合、読み込み用のストリームをオープンします。 モードが `w` の場合、書き込み用のストリームをオープンします。

### 戻り値

成功した場合にストリームリソース、失敗した場合に `false` を返します。

### 例

例1 Pdo\Pgsql::lobOpen() の例

Pdo\Pgsql::lobCreate() の例に続き、 このコードはデータベースからラージオブジェクトを取得し ブラウザに出力します。

    <?php
    $db = new Pdo\Pgsql('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\Pgsql::lobCreate() - 新しいラージオブジェクトを作成する
- Pdo\Pgsql::lobUnlink() - ラージオブジェクトを削除する
- pg_lo_create() - ラージオブジェクトを生成する
- pg_lo_open() - ラージオブジェクトをオープンする

# Pdo\Pgsql::lobUnlink

(PHP 8 >= 8.4.0)

Pdo\Pgsql::lobUnlink — ラージオブジェクトを削除する

### 説明

public function Pdo\Pgsql::lobUnlink(string `$oid`): bool

OID が指すラージオブジェクトをデータベースから削除します。

> 注意: この関数を含むラージオブジェクトへの全ての操作は トランザクション内で行わなければなりません。

### パラメータ

`oid`
  ラージオブジェクトの ID。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 例

例1 Pdo\Pgsql::lobUnlink() の例

Pdo\Pgsql::lobCreate() および Pdo\Pgsql::lobOpen() の例で使用した 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\Pgsql::lobCreate() - 新しいラージオブジェクトを作成する
- Pdo\Pgsql::lobOpen() - 既存のラージオブジェクトのストリームをオープンする
- pg_lo_create() - ラージオブジェクトを生成する
- pg_lo_open() - ラージオブジェクトをオープンする

# Pdo\Pgsql::setNoticeCallback

(PHP 8 >= 8.4.0)

Pdo\Pgsql::setNoticeCallback — バックエンドが生成する通知および警告メッセージを処理するコールバックを設定する

### 説明

public function Pdo\Pgsql::setNoticeCallback(?callable `$callback`): void

バックエンドが生成する通知および警告メッセージを処理するためのコールバックを設定します。 これには、PostgreSQL 本体が出力するメッセージや、 ユーザー定義 SQL 関数で `RAISE` されたメッセージも含まれます。 これらのメッセージを実際に受信できるかは、バックエンド側の設定 `client_min_messages` に依存する点に注意してください。

### パラメータ

`callback`
  `null` を渡すと、ハンドラはデフォルトの状態にリセットされます。

  それ以外の場合、ハンドラは次のシグネチャを持つコールバック関数です:

  function handler(string `$message`): void
  `message`
    バックエンドが生成したメッセージ

### 戻り値

値を返しません。

### 例

例1 Pdo\Pgsql::setNoticeCallback() の例

    <?php
    $pdo = new Pdo\Pgsql('pgsql:dbname=test host=localhost', $user, $pass);

    $pdo->exec('CREATE TABLE parent(id int primary key)');
    $pdo->exec('CREATE TABLE child(id int references parent)');

    $pdo->setNoticeCallback(function ($message) {
        echo $message;
    });

    $pdo->exec('TRUNCATE parent CASCADE');
    ?>

上の例の出力は、 たとえば以下のようになります。

    NOTICE:  truncate cascades to table "child"

## 目次

- Pdo\Pgsql::copyFromArray — PHP の配列から、データをテーブルにコピーする
- Pdo\Pgsql::copyFromFile — ファイルからデータをテーブルにコピーする
- Pdo\Pgsql::copyToArray — データベーステーブルからのデータをPHPの配列にコピーする
- Pdo\Pgsql::copyToFile — テーブルのデータをファイルにコピーする
- Pdo\Pgsql::escapeIdentifier — SQL識別子として使用するために文字列をエスケープする
- Pdo\Pgsql::getNotify — 非同期に通知を取得する
- Pdo\Pgsql::getPid — 接続を処理するバックエンドプロセスのPIDを取得する
- Pdo\Pgsql::lobCreate — 新しいラージオブジェクトを作成する
- Pdo\Pgsql::lobOpen — 既存のラージオブジェクトのストリームをオープンする
- Pdo\Pgsql::lobUnlink — ラージオブジェクトを削除する
- Pdo\Pgsql::setNoticeCallback — バックエンドが生成する通知および警告メッセージを処理するコールバックを設定する

# SQLite PDO ドライバ (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

(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:

# PDO::sqliteCreateAggregate

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo_sqlite >= 1.0.0)

PDO::sqliteCreateAggregate — Pdo\Sqlite::createAggregate() のエイリアス

### 説明

public function PDO::sqliteCreateAggregate(
string `$name`,
callable `$step`,
callable `$finalize`,
int `$numArgs` = -1
): bool

このメソッドは次のメソッドのエイリアスです。 Pdo\Sqlite::createAggregate().

# PDO::sqliteCreateCollation

(PHP 5 >= 5.3.11, PHP 7, PHP 8)

PDO::sqliteCreateCollation — Pdo\Sqlite::createCollation() のエイリアス

### 説明

public function PDO::sqliteCreateCollation(string `$name`, callable `$callback`): bool

このメソッドは次のメソッドのエイリアスです。 Pdo\Sqlite::createCollation().

# PDO::sqliteCreateFunction

(PHP 5 >= 5.1.0, PHP 7, PHP 8, PECL pdo_sqlite >= 1.0.0)

PDO::sqliteCreateFunction — Pdo\Sqlite::createFunction() のエイリアス

### 説明

public function PDO::sqliteCreateFunction(
string `$function_name`,
callable `$callback`,
int `$num_args` = -1,
int `$flags` = 0
): bool

このメソッドは次のメソッドのエイリアスです。 Pdo\Sqlite::createFunction().

### 変更履歴

バージョン | 説明
--- | ---
7.1.4 | `flags` パラメータが追加されました。

## 目次

- PDO_SQLITE DSN — SQLite データベースに接続する
- PDO::sqliteCreateAggregate — Pdo\Sqlite::createAggregate のエイリアス
- PDO::sqliteCreateCollation — Pdo\Sqlite::createCollation のエイリアス
- PDO::sqliteCreateFunction — Pdo\Sqlite::createFunction のエイリアス

# Pdo\Sqlite クラス

(PHP 8 >= 8.4.0)

## はじめに

SQLite PDO ドライバによる接続を示す PDO サブクラスです。

このドライバは SQLite 方言向けに専用の SQL クエリパーサーをサポートしています。 次のものを処理可能です:

- シングルクオート、ダブルクオート、バッククオートで囲まれたリテラルでのクオートの二重化によるエスケープ
- 識別子の角括弧によるクオート
- 2 つのハイフンによるコメント、ネストされていない C 言語形式のコメント

## クラス概要

class Pdo\Sqlite extends PDO {
/* 継承した定数 */
public const int PDO::PARAM_NULL;
public const int PDO::PARAM_BOOL = 5;
public const int PDO::PARAM_INT = 1;
public const int PDO::PARAM_STR = 2;
public const int PDO::PARAM_LOB = 3;
public const int PDO::PARAM_STMT = 4;
public const int PDO::PARAM_INPUT_OUTPUT;
public const int PDO::PARAM_STR_NATL;
public const int PDO::PARAM_STR_CHAR;
public const int PDO::PARAM_EVT_ALLOC;
public const int PDO::PARAM_EVT_FREE;
public const int PDO::PARAM_EVT_EXEC_PRE;
public const int PDO::PARAM_EVT_EXEC_POST;
public const int PDO::PARAM_EVT_FETCH_PRE;
public const int PDO::PARAM_EVT_FETCH_POST;
public const int PDO::PARAM_EVT_NORMALIZE;
public const int PDO::FETCH_DEFAULT;
public const int PDO::FETCH_LAZY;
public const int PDO::FETCH_ASSOC;
public const int PDO::FETCH_NUM;
public const int PDO::FETCH_BOTH;
public const int PDO::FETCH_OBJ;
public const int PDO::FETCH_BOUND;
public const int PDO::FETCH_COLUMN;
public const int PDO::FETCH_CLASS;
public const int PDO::FETCH_INTO;
public const int PDO::FETCH_FUNC;
public const int PDO::FETCH_GROUP;
public const int PDO::FETCH_UNIQUE;
public const int PDO::FETCH_KEY_PAIR;
public const int PDO::FETCH_CLASSTYPE;
public const int PDO::FETCH_SERIALIZE;
public const int PDO::FETCH_PROPS_LATE;
public const int PDO::FETCH_NAMED;
public const int PDO::ATTR_AUTOCOMMIT;
public const int PDO::ATTR_PREFETCH;
public const int PDO::ATTR_TIMEOUT;
public const int PDO::ATTR_ERRMODE;
public const int PDO::ATTR_SERVER_VERSION;
public const int PDO::ATTR_CLIENT_VERSION;
public const int PDO::ATTR_SERVER_INFO;
public const int PDO::ATTR_CONNECTION_STATUS;
public const int PDO::ATTR_CASE;
public const int PDO::ATTR_CURSOR_NAME;
public const int PDO::ATTR_CURSOR;
public const int PDO::ATTR_ORACLE_NULLS;
public const int PDO::ATTR_PERSISTENT;
public const int PDO::ATTR_STATEMENT_CLASS;
public const int PDO::ATTR_FETCH_TABLE_NAMES;
public const int PDO::ATTR_FETCH_CATALOG_NAMES;
public const int PDO::ATTR_DRIVER_NAME;
public const int PDO::ATTR_STRINGIFY_FETCHES;
public const int PDO::ATTR_MAX_COLUMN_LEN;
public const int PDO::ATTR_EMULATE_PREPARES;
public const int PDO::ATTR_DEFAULT_FETCH_MODE;
public const int PDO::ATTR_DEFAULT_STR_PARAM;
public const int PDO::ERRMODE_SILENT;
public const int PDO::ERRMODE_WARNING;
public const int PDO::ERRMODE_EXCEPTION;
public const int PDO::CASE_NATURAL;
public const int PDO::CASE_LOWER;
public const int PDO::CASE_UPPER;
public const int PDO::NULL_NATURAL;
public const int PDO::NULL_EMPTY_STRING;
public const int PDO::NULL_TO_STRING;
public const string PDO::ERR_NONE;
public const int PDO::FETCH_ORI_NEXT;
public const int PDO::FETCH_ORI_PRIOR;
public const int PDO::FETCH_ORI_FIRST;
public const int PDO::FETCH_ORI_LAST;
public const int PDO::FETCH_ORI_ABS;
public const int PDO::FETCH_ORI_REL;
public const int PDO::CURSOR_FWDONLY;
public const int PDO::CURSOR_SCROLL;
/* 定数 */
public const int DETERMINISTIC;
public const int OPEN_READONLY;
public const int OPEN_READWRITE;
public const int OPEN_CREATE;
public const int ATTR_OPEN_FLAGS;
public const int ATTR_READONLY_STATEMENT;
public const int ATTR_EXTENDED_RESULT_CODES;
/* メソッド */
public function createAggregate(
string `$name`,
callable `$step`,
callable `$finalize`,
int `$numArgs` = -1
): bool
public function createCollation(string `$name`, callable `$callback`): bool
public function createFunction(
string `$function_name`,
callable `$callback`,
int `$num_args` = -1,
int `$flags` = 0
): bool
public function loadExtension(string `$name`): void
public function openBlob(
string `$table`,
string `$column`,
int `$rowid`,
?string `$dbname` = "main",
int `$flags` = `Pdo\Sqlite::OPEN_READONLY`
): resource|false
/* 継承したメソッド */
public function PDO::__construct(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
?array `$options` = `null`
)
public function PDO::beginTransaction(): bool
public function PDO::commit(): bool
public static function PDO::connect(
string `$dsn`,
?string `$username` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
?array `$options` = `null`
): static
public function PDO::errorCode(): ?string
public function PDO::errorInfo(): array
public function PDO::exec(string `$statement`): int|false
public function PDO::getAttribute(int `$attribute`): mixed
public static function PDO::getAvailableDrivers(): array
public function PDO::inTransaction(): bool
public function PDO::lastInsertId(?string `$name` = `null`): string|false
public function PDO::prepare(string `$query`, array `$options` = []): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = `null`): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_COLUMN, int `$colno`): PDOStatement|false
public function PDO::query(
string `$query`,
?int `$fetchMode` = PDO::FETCH_CLASS,
string `$classname`,
array `$constructorArgs`
): PDOStatement|false
public function PDO::query(string `$query`, ?int `$fetchMode` = PDO::FETCH_INTO, object `$object`): PDOStatement|false
public function PDO::quote(string `$string`, int `$type` = `PDO::PARAM_STR`): string|false
public function PDO::rollBack(): bool
public function PDO::setAttribute(int `$attribute`, mixed `$value`): bool
}

## 定義済み定数

`Pdo\Sqlite::DETERMINISTIC`
`Pdo\Sqlite::OPEN_READONLY`
`Pdo\Sqlite::OPEN_READWRITE`
`Pdo\Sqlite::OPEN_CREATE`
`Pdo\Sqlite::ATTR_OPEN_FLAGS`
`Pdo\Sqlite::ATTR_READONLY_STATEMENT`
`Pdo\Sqlite::ATTR_EXTENDED_RESULT_CODES`

# Pdo\Sqlite::createAggregate

(PHP 8 >= 8.4.0)

Pdo\Sqlite::createAggregate — SQL 文で使用するユーザー定義集約関数を登録する

### 説明

public function Pdo\Sqlite::createAggregate(
string `$name`,
callable `$step`,
callable `$finalize`,
int `$numArgs` = -1
): bool

このメソッドは Pdo\Sqlite::createFunction() と似ていますが、クエリのすべての行を集約する関数を登録する点が 異なります。

この関数と Pdo\Sqlite::createFunction() の最大の違いは、集約関数の登録には 2 つの関数が必要であるということです。

ヒント

このメソッドを使用してネイティブ SQL 関数を上書きすることができます。

### パラメータ

`name`
  SQL 文で使用する関数の名前。
`step`
  結果セットの各行を処理するコールバック関数。 この関数は、結果を蓄積して集約コンテキストに保存しなければなりません。

  定義は次のとおりです:

  function step(
  mixed `$context`,
  int `$rownumber`,
  mixed `$value`,
  mixed `...$values`
  ): mixed
  `context`
    最初の行では `null` 2行目以降では、この関数が前回返した値です。 この値で集約の状態を管理します。
  `rownumber`
    現在の行番号
  `value`
    集約関数に渡されるはじめの引数
  `values`
    集約関数に渡されるふたつめ以降の引数
  この関数の戻り値を、次の関数呼び出し、または ファイナライズ関数の`context` 引数として 使います。
`finalize`
  すべての行が処理された後で呼び出されるコールバック関数。 ここでは、集約コンテキストからデータを取得して結果を返します。 この関数が返す値は、SQLite が理解できる形式 (すなわち スカラー型) でなければなりません。

  定義は次のとおりです:

  function fini(mixed `$context`, int `$rowcount`): mixed
  `context`

    ステップ関数の最後の戻り値

  `rowcount`

    ステップ関数が処理した行数

  この関数の戻り値が、 集約関数全体の戻り値となります。
`numArgs`
  コールバック関数があらかじめ定義済みの引数を受け取る場合に、 SQLite のパーサーに渡すヒント。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 例

例1 Pdo\Sqlite::createAggregate() example

この例では、SQLクエリの中で使用できる `max_length` という名前のユーザー定義集約関数を作成しています。

この例では、`max_length` という集約関数を 作成しています。この関数はテーブルの特定のカラム内で 最も長い文字列の長さを計算します。 各行に対し `max_len_step` 関数が呼ばれ、 その際に `$context` パラメータが渡されます。 この context パラメータには、他の PHP 変数と同様 array や object などを格納できます。 この例では、これまでの中で最大の文字列長を格納するために利用しています。 もし $string が現在の最大値よりも長ければ、 context に格納した最大長を新たな値で更新します。

全ての行が処理された後、 SQLite は集約関数の結果を計算するため `max_len_finalize` 関数を呼び出します。 `$context` 内のデータに基づいて何らかの計算を行うことも可能です。 この例では、結果はクエリの進行中に計算されているため、 context の値をそのまま返すことができます。

    <?php
    $data = [
       'one',
       'two',
       'three',
       'four',
       'five',
       'six',
       'seven',
       'eight',
       'nine',
       'ten',
    ];
    $db = new Pdo\Sqlite('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, $row_number, $string)
    {
        if (strlen($string) > $context) {
            $context = strlen($string);
        }
        return $context;
    }

    function max_len_finalize($context, $row_count)
    {
        return $context === null ? 0 : $context;
    }

    $db->createAggregate('max_len', 'max_len_step', 'max_len_finalize');

    var_dump($db->query('SELECT max_len(a) from strings')->fetchAll());

    ?>

ヒント

結果の値を context に蓄積し、最後に一括で処理する方法は推奨 「しません」。これは、SQLite のメモリ消費量が大きくなるからです。 仮に 32 バイトの長さのデータが百万件あったとして、 それを蓄積しておくのにどれだけのメモリが必要になるか 考えてみましょう。

### 参考

- Pdo\Sqlite::createFunction() - SQL 文で使用するユーザー定義関数を登録する
- Pdo\Sqlite::createCollation() - SQL文で文字列比較関数として使うユーザー定義関数を登録する
- sqlite_create_function()
- sqlite_create_aggregate()

# Pdo\Sqlite::createCollation

(PHP 8 >= 8.4.0)

Pdo\Sqlite::createCollation — SQL文で文字列比較関数として使うユーザー定義関数を登録する

### 説明

public function Pdo\Sqlite::createCollation(string `$name`, callable `$callback`): bool

このメソッドは Pdo\Sqlite::createFunction() と似ていますが、文字列比較関数を登録する点が異なります。

### パラメータ

`name`
  作成または再定義する文字列比較 SQL 関数の名前
`callback`
  文字列比較の動作を定義するコールバック関数です。 この関数は2つのstringを受け取り、 1番目の文字列が2番目の文字列より前に並ぶ場合 `-1`、 同じ並び順の場合 `0`、 後に並ぶ場合 `1` を返さなければなりません。 これに似た振る舞いをする組み込み関数として、strcmp() が挙げられます。

  This function need to be defined as:

  function collation(string `$string1`, string `$string2`): int

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 例

例1 Pdo\Sqlite::createCollation() の例

    <?php
    $db = new Pdo\Sqlite('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

### 参考

- Pdo\Sqlite::createFunction() - SQL 文で使用するユーザー定義関数を登録する
- Pdo\Sqlite::createAggregate() - SQL 文で使用するユーザー定義集約関数を登録する
- sqlite_create_function()
- sqlite_create_aggregate()

# Pdo\Sqlite::createFunction

(PHP 8 >= 8.4.0)

Pdo\Sqlite::createFunction — SQL 文で使用するユーザー定義関数を登録する

### 説明

public function Pdo\Sqlite::createFunction(
string `$function_name`,
callable `$callback`,
int `$num_args` = -1,
int `$flags` = 0
): bool

PHP 関数を、ユーザー定義関数として SQLite に登録します。 登録した関数は、SQL 文の中で使用することが可能です。 ユーザー定義関数は、関数をコールできるあらゆる SQL 文 (`SELECT`、`UPDATE` 、トリガなど) から呼び出せます。

ヒント

このメソッドを使用してネイティブ SQL 関数を上書きすることができます。

### パラメータ

`function_name`
  SQL 文で使用する関数の名前。
`callback`
  定義した SQL 関数を処理するコールバック関数。

  > 注意: この関数が返す値は、SQLite が理解できる形式 (すなわち スカラー型) でなければなりません。

  コールバック関数の定義は次のとおりです:

  function callback(mixed `$value`, mixed `...$values`): mixed
  `value`

    SQL関数に渡す最初の引数

  `values`

    SQL関数に渡す2つ目以降の引数

`num_args`
  SQL 関数がとる引数の数。 このパラメータが `-1` の場合、 SQL 関数は任意の数の引数を取ることができます。
`flags`
  ビット単位のフラグの組み合わせ。 現在は、`Pdo\Sqlite::DETERMINISTIC` だけがサポートされています。 これは、単一のSQLステートメント内では、 同じ入力に対して常に同じ結果を返すことを指定します。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 例

例1 Pdo\Sqlite::createFunction() の例

この例では、文字列の SHA256 ハッシュを計算し それを反転する関数を使っています。SQL 文を実行すると、 この関数によって変換されたファイル名が $rows に格納され返ります。

この手法の素晴らしい点は、クエリの後に `foreach` ループを用いて結果を処理する必要がないことです。

    <?php
    function sha256_and_reverse($string)
    {
        return strrev(hash('sha256', $string));
    }

    $db = new Pdo\Sqlite('sqlite::sqlitedb');
    $db->createFunction('sha256rev', 'sha256_and_reverse', 1);
    $rows = $db->query('SELECT sha256rev(filename) FROM files')->fetchAll();
    ?>

### 参考

- Pdo\Sqlite::createAggregate() - SQL 文で使用するユーザー定義集約関数を登録する
- Pdo\Sqlite::createCollation() - SQL文で文字列比較関数として使うユーザー定義関数を登録する
- sqlite_create_function()
- sqlite_create_aggregate()

# Pdo\Sqlite::loadExtension

(PHP 8 >= 8.4.0)

Pdo\Sqlite::loadExtension — Description

### 説明

public function Pdo\Sqlite::loadExtension(string `$name`): void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

Description.

### パラメータ

`name`
  Description.

### 戻り値

値を返しません。

### エラー / 例外

When does this function issue `E_*` level errors, and/or throw Exceptions.

### 例

例1 Pdo\Sqlite::loadExtension() example

Description.

    <?php
    echo "Code example";
    ?>

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

    Code example

### 注意

> 注意: Any notes that don't fit anywhere else should go here.

### 参考

- ClassName::otherMethodName()
- some_function()

# Pdo\Sqlite::openBlob

(PHP 8 >= 8.4.0)

Pdo\Sqlite::openBlob — Description

### 説明

public function Pdo\Sqlite::openBlob(
string `$table`,
string `$column`,
int `$rowid`,
?string `$dbname` = "main",
int `$flags` = `Pdo\Sqlite::OPEN_READONLY`
): resource|false
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

Description.

### パラメータ

`table`
  Description.
`column`
  Description.
`rowid`
  Description.
`dbname`
  Description.
`flags`
  One of the `Pdo\Sqlite::OPEN_*`

### 戻り値

Description.

### エラー / 例外

When does this function issue `E_*` level errors, and/or throw Exceptions.

### 例

例1 Pdo\Sqlite::openBlob() example

Description.

    <?php
    echo "Code example";
    ?>

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

    Code example

### 注意

> 注意: Any notes that don't fit anywhere else should go here.

### 参考

- ClassName::otherMethodName()
- some_function()

## 目次

- Pdo\Sqlite::createAggregate — SQL 文で使用するユーザー定義集約関数を登録する
- Pdo\Sqlite::createCollation — SQL文で文字列比較関数として使うユーザー定義関数を登録する
- Pdo\Sqlite::createFunction — SQL 文で使用するユーザー定義関数を登録する
- Pdo\Sqlite::loadExtension — Description
- Pdo\Sqlite::openBlob — Description

- インストール/設定
  - インストール手順
  - 実行時設定
- 定義済み定数
  - フェッチモード
- 接続、および接続の管理
- トランザクションおよび自動コミット
- プリペアドステートメントおよびストアドプロシージャ
- エラーおよびエラー処理
- ラージオブジェクト (LOB)
- PDO — PDO クラス
  - PDO::beginTransaction — トランザクションを開始する
  - PDO::commit — トランザクションをコミットする
  - PDO::connect — データベースに接続しドライバが対応する PDO サブクラスを返す
  - 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 ドライバ (PDO_CUBRID)
  - MS SQL Server PDO ドライバ — Microsoft SQL Server および Sybase PDO ドライバ (PDO_DBLIB)
  - Pdo\Dblib — Pdo\Dblib クラス
  - Firebird PDO ドライバ — Firebird PDO ドライバ (PDO_FIREBIRD)
  - Pdo\Firebird — Pdo\Firebird クラス
  - IBM PDO ドライバ — IBM PDO ドライバ (PDO_IBM)
  - Informix PDO ドライバ — Informix PDO ドライバ (PDO_INFORMIX)
  - MySQL PDO ドライバ — MySQL PDO ドライバ (PDO_MYSQL)
  - Pdo\Mysql — Pdo\Mysql クラス
  - MS SQL Server PDO ドライバ — Microsoft SQL Server PDO ドライバ (PDO_SQLSRV)
  - Oracle PDO ドライバ — Oracle PDO ドライバ (PDO_OCI)
  - ODBC and DB2 PDO ドライバ — ODBC and DB2 PDO ドライバ (PDO_ODBC)
  - Pdo\Odbc — Pdo\Odbc クラス
  - PostgreSQL PDO ドライバ — PostgreSQL PDO ドライバ (PDO_PGSQL)
  - Pdo\Pgsql — Pdo\Pgsql クラス
  - SQLite PDO ドライバ — SQLite PDO ドライバ (PDO_SQLITE)
  - Pdo\Sqlite — Pdo\Sqlite クラス

- DBA — データベース (dbm 形式) 抽象化レイヤ
  - インストール/設定
  - 定義済み定数
  - 例
  - Dba\Connection — Dba\Connection クラス
  - DBA 関数
- ODBC — ODBC (Unified)
  - インストール/設定
  - 定義済み定数
  - ODBC 関数
  - Odbc\Connection — Odbc\Connection クラス
  - Odbc\Result — Odbc\Result クラス
- PDO — PHP Data Objects
  - インストール/設定
  - 定義済み定数
  - 接続、および接続の管理
  - トランザクションおよび自動コミット
  - プリペアドステートメントおよびストアドプロシージャ
  - エラーおよびエラー処理
  - ラージオブジェクト (LOB)
  - PDO — PDO クラス
  - PDOStatement — PDOStatement クラス
  - PDOException — PDOException クラス
  - PDORow — PDORow クラス
  - PDO ドライバ

# ベンダー固有のモジュール

# CUBRID

# はじめに

これらの関数により、CUBRID データベースサーバーにアクセスできます。 CUBRID についての詳細は、» CUBRIDで見つかります。

CUBRID についてのドキュメントは、» 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 をお読みください。

## 実行時設定

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 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 as 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 two 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

(PECL CUBRID >= 8.3.0)

cubrid_bind — Bind variables to a prepared statement as parameters

### 説明

function 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 environment, the `bind_value_type` must be included in the cubrid_bind() function.

The following table shows the types of substitute values.

CUBRID Bind Data 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

# cubrid_close_prepare

(PECL CUBRID >= 8.3.0)

cubrid_close_prepare — Close the request handle

### 説明

function 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

# cubrid_close_request

(PECL CUBRID >= 8.3.0)

cubrid_close_request — Close the request handle

### 説明

function 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

# cubrid_col_get

(PECL CUBRID >= 8.3.0)

cubrid_col_get — Get contents of collection type column using OID

### 説明

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

# cubrid_col_size

(PECL CUBRID >= 8.3.0)

cubrid_col_size — Get the number of elements in collection type column using OID

### 説明

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

# cubrid_column_names

(PECL CUBRID >= 8.3.0)

cubrid_column_names — Get the column names in result

### 説明

function 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

# cubrid_column_types

(PECL CUBRID >= 8.3.0)

cubrid_column_types — Get column types in result

### 説明

function 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

# cubrid_commit

(PECL CUBRID >= 8.3.0)

cubrid_commit — Commit a transaction

### 説明

function 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

# cubrid_connect

(PECL CUBRID >= 8.3.1)

cubrid_connect — Open a connection to a CUBRID Server

### 説明

function 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

# cubrid_connect_with_url

(PECL CUBRID >= 8.3.1)

cubrid_connect_with_url — Establish the environment for connecting to CUBRID server

### 説明

function 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 the requested query is sent to the server. 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

# cubrid_current_oid

(PECL CUBRID >= 8.3.0)

cubrid_current_oid — Get OID of the current cursor location

### 説明

function 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

# cubrid_disconnect

(PECL CUBRID >= 8.3.0)

cubrid_disconnect — Close a database connection

### 説明

function 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

# cubrid_drop

(PECL CUBRID >= 8.3.0)

cubrid_drop — Delete an instance using OID

### 説明

function 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

# cubrid_error_code

(PECL CUBRID >= 8.3.0)

cubrid_error_code — Get error code for the most recent function call

### 説明

function 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

# cubrid_error_code_facility

(PECL CUBRID >= 8.3.0)

cubrid_error_code_facility — Get the facility code of error

### 説明

function 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

# cubrid_error_msg

(PECL CUBRID >= 8.3.0)

cubrid_error_msg — Get last error message for the most recent function call

### 説明

function 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

# cubrid_execute

(PECL CUBRID >= 8.3.0)

cubrid_execute — Execute a prepared SQL statement

### 説明

function cubrid_execute(resource `$conn_identifier`, string `$sql`, int `$option` = 0): resource
function 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 is selected. 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

# cubrid_fetch

(PECL CUBRID >= 8.3.0)

cubrid_fetch — Fetch the next row from a result set

### 説明

function 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

# cubrid_free_result

(PECL CUBRID >= 8.3.0)

cubrid_free_result — Free the memory occupied by the result data

### 説明

function 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"
    }

# cubrid_get

(PECL CUBRID >= 8.3.0)

cubrid_get — Get a column using OID

### 説明

function 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

# cubrid_get_autocommit

(PECL CUBRID >= 8.4.0)

cubrid_get_autocommit — Get auto-commit mode of the connection

### 説明

function 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

# cubrid_get_charset

(PECL CUBRID >= 8.3.0)

cubrid_get_charset — Return the current CUBRID connection charset

### 説明

function 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

# cubrid_get_class_name

(PECL CUBRID >= 8.3.0)

cubrid_get_class_name — Get the class name using OID

### 説明

function 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

# cubrid_get_client_info

(PECL CUBRID >= 8.3.0)

cubrid_get_client_info — Return the client library version

### 説明

function 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

# cubrid_get_db_parameter

(PECL CUBRID >= 8.3.0)

cubrid_get_db_parameter — Returns the CUBRID database parameters

### 説明

function 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

# cubrid_get_query_timeout

(PECL CUBRID >= 8.4.1)

cubrid_get_query_timeout — Get the query timeout value of the request

### 説明

function 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

# cubrid_get_server_info

(PECL CUBRID >= 8.3.0)

cubrid_get_server_info — Return the CUBRID server version

### 説明

function 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

# cubrid_insert_id

(PECL CUBRID >= 8.3.0)

cubrid_insert_id — Return the ID generated for the last updated `AUTO_INCREMENT` column

### 説明

function 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"

# cubrid_is_instance

(PECL CUBRID >= 8.3.0)

cubrid_is_instance — Check whether the instance pointed by OID exists

### 説明

function 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

# cubrid_lob_close

(PECL CUBRID >= 8.3.1)

cubrid_lob_close — Close BLOB/CLOB data

### 説明

function 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

# cubrid_lob_export

(PECL CUBRID >= 8.3.1)

cubrid_lob_export — Export BLOB/CLOB data to file

### 説明

function 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

# cubrid_lob_get

(PECL CUBRID >= 8.3.1)

cubrid_lob_get — Get BLOB/CLOB data

### 説明

function 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

# cubrid_lob_send

(PECL CUBRID >= 8.3.1)

cubrid_lob_send — Read BLOB/CLOB data and send straight to browser

### 説明

function 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

# cubrid_lob_size

(PECL CUBRID >= 8.3.1)

cubrid_lob_size — Get BLOB/CLOB data size

### 説明

function 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

# 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

### 説明

function 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

# cubrid_lob2_close

(PECL CUBRID >= 8.4.1)

cubrid_lob2_close — Close LOB object

### 説明

function 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

# cubrid_lob2_export

(PECL CUBRID >= 8.4.1)

cubrid_lob2_export — Export the lob object to a file

### 説明

function 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

# cubrid_lob2_import

(PECL CUBRID >= 8.4.1)

cubrid_lob2_import — Import BLOB/CLOB data from a file

### 説明

function 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 does not exist, 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

# cubrid_lob2_new

(PECL CUBRID >= 8.4.1)

cubrid_lob2_new — Create a lob object

### 説明

function 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

# cubrid_lob2_read

(PECL CUBRID >= 8.4.1)

cubrid_lob2_read — Read from BLOB/CLOB data

### 説明

function 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

# cubrid_lob2_seek

(PECL CUBRID >= 8.4.1)

cubrid_lob2_seek — Move the cursor of a lob object

### 説明

function 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

# cubrid_lob2_seek64

(PECL CUBRID >= 8.4.1)

cubrid_lob2_seek64 — Move the cursor of a lob object

### 説明

function 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

# cubrid_lob2_size

(PECL CUBRID >= 8.4.1)

cubrid_lob2_size — Get a lob object's size

### 説明

function 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

# cubrid_lob2_size64

(PECL CUBRID >= 8.4.1)

cubrid_lob2_size64 — Get a lob object's size

### 説明

function 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

# cubrid_lob2_tell

(PECL CUBRID >= 8.4.1)

cubrid_lob2_tell — Tell the cursor position of the LOB object

### 説明

function 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

# cubrid_lob2_tell64

(PECL CUBRID >= 8.4.1)

cubrid_lob2_tell64 — Tell the cursor position of the LOB object

### 説明

function 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

# cubrid_lob2_write

(PECL CUBRID >= 8.4.1)

cubrid_lob2_write — Write to a lob object

### 説明

function 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

# cubrid_lock_read

(PECL CUBRID >= 8.3.0)

cubrid_lock_read — Set a read lock on the given OID

### 説明

function 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

# cubrid_lock_write

(PECL CUBRID >= 8.3.0)

cubrid_lock_write — Set a write lock on the given OID

### 説明

function 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

# cubrid_move_cursor

(PECL CUBRID >= 8.3.0)

cubrid_move_cursor — Move the cursor in the result

### 説明

function 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

# cubrid_next_result

(PECL CUBRID >= 8.4.0)

cubrid_next_result — Get result of next query when executing multiple SQL statements

### 説明

function 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

# cubrid_num_cols

(PECL CUBRID >= 8.3.0)

cubrid_num_cols — Return the number of columns in the result set

### 説明

function 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

# cubrid_num_rows

(PECL CUBRID >= 8.3.0)

cubrid_num_rows — Get the number of rows in the result set

### 説明

function 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

# cubrid_pconnect

(PECL CUBRID >= 8.3.1)

cubrid_pconnect — Open a persistent connection to a CUBRID server

### 説明

function 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_pconnect() 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

# cubrid_pconnect_with_url

(PECL CUBRID >= 8.3.1)

cubrid_pconnect_with_url — Open a persistent connection to CUBRID server

### 説明

function 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

# cubrid_prepare

(PECL CUBRID >= 8.3.0)

cubrid_prepare — Prepare a SQL statement for execution

### 説明

function cubrid_prepare(resource `$conn_identifier`, string `$prepare_stmt`, int `$option` = 0): resource

The cubrid_prepare() function compiles a SQL statement for a given connection handle and returns a handle that represents the pre-compiled statement.

A prepared statement can be executed several times, which is efficient for repeated execution or for processing long data. Only a single statement can be used, and a parameter can be marked with a question mark (`?`) at the appropriate place in the SQL statement. Add a parameter when binding a value in the `VALUES` clause of an `INSERT` statement or in the `WHERE` clause. Note that a value can be bound to a parameter only by using the cubrid_bind() function.

### パラメータ

`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

# cubrid_put

(PECL CUBRID >= 8.3.0)

cubrid_put — Update a column using OID

### 説明

function 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

# cubrid_rollback

(PECL CUBRID >= 8.3.0)

cubrid_rollback — Roll back a transaction

### 説明

function 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

# cubrid_schema

(PECL CUBRID >= 8.3.0)

cubrid_schema — Get the requested schema information

### 説明

function 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"
      }
    }

# cubrid_seq_drop

(PECL CUBRID >= 8.3.0)

cubrid_seq_drop — Delete an element from sequence type column using OID

### 説明

function 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

# cubrid_seq_insert

(PECL CUBRID >= 8.3.0)

cubrid_seq_insert — Insert an element to a sequence type column using OID

### 説明

function cubrid_seq_insert(
resource `$conn_identifier`,
string `$oid`,
string `$attr_name`,
int `$index`,
string `$seq_element`
): bool

The cubrid_seq_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

# cubrid_seq_put

(PECL CUBRID >= 8.3.0)

cubrid_seq_put — Update the element value of sequence type column using OID

### 説明

function 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

# cubrid_set_add

(PECL CUBRID >= 8.3.0)

cubrid_set_add — Insert a single element to set type column using OID

### 説明

function 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

# cubrid_set_autocommit

(PECL CUBRID >= 8.4.0)

cubrid_set_autocommit — Set autocommit mode of the connection

### 説明

function 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 turned 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

# cubrid_set_db_parameter

(PECL CUBRID >= 8.4.0)

cubrid_set_db_parameter — Sets the CUBRID database parameters

### 説明

function 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

# cubrid_set_drop

(PECL CUBRID >= 8.3.0)

cubrid_set_drop — Delete an element from set type column using OID

### 説明

function 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

# cubrid_set_query_timeout

(PECL CUBRID >= 8.4.1)

cubrid_set_query_timeout — Set the timeout time of query execution

### 説明

function 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

# cubrid_version

(PECL CUBRID >= 8.3.0)

cubrid_version — Get the CUBRID PHP module's version

### 説明

function 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_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

(PECL CUBRID >= 8.3.0)

cubrid_affected_rows — Return the number of rows affected by the last SQL statement

### 説明

function cubrid_affected_rows(resource `$conn_identifier` = ?): int
function 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 opened 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!";
    ?>

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

    int(10)
    int(10)
    int(10)
    done!

### 参考

- cubrid_execute() - Execute a prepared SQL statement

# cubrid_client_encoding

(PECL CUBRID >= 8.3.1)

cubrid_client_encoding — Return the current CUBRID connection charset

### 説明

function 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

# cubrid_close

(PECL CUBRID >= 8.3.1)

cubrid_close — Close CUBRID connection

### 説明

function 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

# cubrid_data_seek

(PECL CUBRID >= 8.3.0)

cubrid_data_seek — Move the internal row pointer of the CUBRID result

### 説明

function 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 currently 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"
    }

# cubrid_db_name

(PECL CUBRID >= 8.3.1)

cubrid_db_name — Get db name from results of cubrid_list_dbs

### 説明

function 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

# cubrid_errno

(PECL CUBRID >= 8.3.1)

cubrid_errno — Return the numerical value of the error message from previous CUBRID operation

### 説明

function 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

# cubrid_error

(PECL CUBRID >= 8.3.1)

cubrid_error — Get the error message

### 説明

function 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

# cubrid_fetch_array

(PECL CUBRID >=8.3.0)

cubrid_fetch_array — Fetch a result row as an associative array, a numeric array, or both

### 説明

function 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

# cubrid_fetch_assoc

(PECL CUBRID >= 8.3.0)

cubrid_fetch_assoc — Return the associative array that corresponds to the fetched row

### 説明

function 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

# cubrid_fetch_field

(PECL CUBRID >= 8.3.1)

cubrid_fetch_field — Get column information from a result and return as an object

### 説明

function 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 a 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

# 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

### 説明

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

# cubrid_fetch_object

(PECL CUBRID >= 8.3.0)

cubrid_fetch_object — Fetch the next row and return it as an object

### 説明

function 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

# cubrid_fetch_row

(PECL CUBRID >= 8.3.0)

cubrid_fetch_row — Return a numerical array with the values of the current row

### 説明

function 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

# cubrid_field_flags

(PECL CUBRID >= 8.3.0)

cubrid_field_flags — Return a string with the flags of the given field offset

### 説明

function 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

# cubrid_field_len

(PECL CUBRID >= 8.3.0)

cubrid_field_len — Get the maximum length of the specified field

### 説明

function 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

# cubrid_field_name

(PECL CUBRID >= 8.3.0)

cubrid_field_name — Return the name of the specified field index

### 説明

function 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

# cubrid_field_seek

(PECL CUBRID >= 8.3.0)

cubrid_field_seek — Move the result set cursor to the specified field offset

### 説明

function 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

# cubrid_field_table

(PECL CUBRID >= 8.3.0)

cubrid_field_table — Return the name of the table of the specified field

### 説明

function 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

# cubrid_field_type

(PECL CUBRID >= 8.3.0)

cubrid_field_type — Return the type of the column corresponding to the given field offset

### 説明

function 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

# cubrid_list_dbs

(PECL CUBRID >= 8.3.0)

cubrid_list_dbs — Return an array with the list of all existing CUBRID databases

### 説明

function 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"
    }

# cubrid_num_fields

(PECL CUBRID >= 8.3.0)

cubrid_num_fields — Return the number of columns in the result set

### 説明

function 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

# cubrid_ping

(PECL CUBRID >= 8.3.1)

cubrid_ping — Ping a server connection or reconnect if there is no connection

### 説明

function 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 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);
    ?>

# cubrid_query

(PECL CUBRID >= 8.3.1)

cubrid_query — Send a CUBRID query

### 説明

function 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

# 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

### 説明

function 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{|}~"
    }

# cubrid_result

(PECL CUBRID >= 8.3.0)

cubrid_result — Return the value of a specific field in a specific row

### 説明

function 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"

# cubrid_unbuffered_query

(PECL CUBRID >= 8.3.0)

cubrid_unbuffered_query — Perform a query without fetching the results into memory

### 説明

function 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_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

(PECL CUBRID >= 8.3.0)

cubrid_load_from_glo — Read data from a GLO instance and save it in a file

### 説明

function 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

# cubrid_new_glo

(PECL CUBRID >= 8.3.0)

cubrid_new_glo — Create a glo instance

### 説明

function 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

# cubrid_save_to_glo

(PECL CUBRID >= 8.3.0)

cubrid_save_to_glo — Save requested file in a GLO instance

### 説明

function 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

# cubrid_send_glo

(PECL CUBRID >= 8.3.0)

cubrid_send_glo — Read data from glo and send it to std output

### 説明

function 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

## 目次

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

# dBase

# はじめに

> 注意:

> この拡張モジュールは » 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.

# インストール/設定

## 目次

- インストール手順
- リソース型

## インストール手順

この 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

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_add_record — Adds a record to a database

### 説明

function 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` を返します。

### 変更履歴

バージョン | 説明
--- | ---
PECL 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

# dbase_close

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_close — Closes a database

### 説明

function dbase_close(resource `$database`): bool

Closes the given database resource.

### パラメータ

`database`

  The database resource, returned by dbase_open() or dbase_create().

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
PECL 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

# dbase_create

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_create — Creates a database

### 説明

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

### 変更履歴

バージョン | 説明
--- | ---
PECL dbase 7.0.0 | The `type` parameter has been added.
PECL 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

# dbase_delete_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_delete_record — Deletes a record from a database

### 説明

function 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` を返します。

### 変更履歴

バージョン | 説明
--- | ---
PECL 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

# dbase_get_header_info

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_get_header_info — Gets the header info of a database

### 説明

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

### 変更履歴

バージョン | 説明
--- | ---
PECL 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);
    ?>

# 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

### 説明

function 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`.

### 変更履歴

バージョン | 説明
--- | ---
PECL 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

# 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

### 説明

function 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`.

### 変更履歴

バージョン | 説明
--- | ---
PECL 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

# dbase_numfields

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_numfields — Gets the number of fields of a database

### 説明

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

### 変更履歴

バージョン | 説明
--- | ---
PECL 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

# dbase_numrecords

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_numrecords — Gets the number of records in a database

### 説明

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

### 変更履歴

バージョン | 説明
--- | ---
PECL 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

# dbase_open

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_open — Opens a database

### 説明

function 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` を返します.

### 変更履歴

バージョン | 説明
--- | ---
PECL 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

# dbase_pack

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_pack — Packs a database

### 説明

function 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` を返します。

### 変更履歴

バージョン | 説明
--- | ---
PECL 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

# dbase_replace_record

(PHP 5 < 5.3.0, dbase 5, dbase 7)

dbase_replace_record — Replaces a record in a database

### 説明

function 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` を返します。

### 変更履歴

バージョン | 説明
--- | ---
PECL 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

## 目次

- 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

- インストール/設定
  - インストール手順
  - リソース型
- 定義済み定数
- 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

# Firebird/InterBase

# はじめに

警告

この拡張モジュールは、メンテナンスされておらず開発が止まっています。 しかし、ソースコードは 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 以降をサポートします。

# インストール/設定

## 目次

- インストール手順
- 実行時設定

## インストール手順

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 7.4.0

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://github.com/FirebirdSQL/php-firebird.

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

(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

# 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

# fbird_backup

(PHP 5, PHP 7 < 7.4.0)

fbird_backup — のエイリアス ibase_backup()

### 説明

この関数は次の関数のエイリアスです。 ibase_backup().

# 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

# fbird_blob_cancel

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_cancel — Cancel creating blob

### 説明

function 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

# 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

# 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

# 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

# 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

# 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

# fbird_blob_info

(PHP 5, PHP 7 < 7.4.0)

fbird_blob_info — のエイリアス ibase_blob_info()

### 説明

この関数は次の関数のエイリアスです。 ibase_blob_info().

# 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

# fbird_close

(PHP 5, PHP 7 < 7.4.0)

fbird_close — のエイリアス ibase_close()

### 説明

この関数は次の関数のエイリアスです。 ibase_close().

### 参考

- fbird_connect() - のエイリアス ibase_connect
- fbird_pconnect() - のエイリアス ibase_pconnect

# fbird_commit

(PHP 5, PHP 7 < 7.4.0)

fbird_commit — のエイリアス ibase_commit()

### 説明

この関数は次の関数のエイリアスです。 ibase_commit().

# fbird_commit_ret

(PHP 5, PHP 7 < 7.4.0)

fbird_commit_ret — のエイリアス ibase_commit_ret()

### 説明

この関数は次の関数のエイリアスです。 ibase_commit_ret().

# fbird_connect

(PHP 5, PHP 7 < 7.4.0)

fbird_connect — のエイリアス ibase_connect()

### 説明

この関数は次の関数のエイリアスです。 ibase_connect().

### 参考

- fbird_pconnect() - のエイリアス ibase_pconnect
- fbird_close() - のエイリアス ibase_close

# fbird_db_info

(PHP 5, PHP 7 < 7.4.0)

fbird_db_info — のエイリアス ibase_db_info()

### 説明

この関数は次の関数のエイリアスです。 ibase_db_info().

# 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

# 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

# fbird_errcode

(PHP 5, PHP 7 < 7.4.0)

fbird_errcode — のエイリアス ibase_errcode()

### 説明

この関数は次の関数のエイリアスです。 ibase_errcode().

### 参考

- fbird_errmsg() - のエイリアス ibase_errmsg

# fbird_errmsg

(PHP 5, PHP 7 < 7.4.0)

fbird_errmsg — のエイリアス ibase_errmsg()

### 説明

この関数は次の関数のエイリアスです。 ibase_errmsg().

### 参考

- fbird_errcode() - のエイリアス ibase_errcode

# fbird_execute

(PHP 5, PHP 7 < 7.4.0)

fbird_execute — のエイリアス ibase_execute()

### 説明

この関数は次の関数のエイリアスです。 ibase_execute().

### 参考

- fbird_query() - のエイリアス ibase_query

# 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

# 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

# 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

# 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

# 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

# fbird_free_query

(PHP 5, PHP 7 < 7.4.0)

fbird_free_query — のエイリアス ibase_free_query()

### 説明

この関数は次の関数のエイリアスです。 ibase_free_query().

# fbird_free_result

(PHP 5, PHP 7 < 7.4.0)

fbird_free_result — のエイリアス ibase_free_result()

### 説明

この関数は次の関数のエイリアスです。 ibase_free_result().

# fbird_gen_id

(PHP 5, PHP 7 < 7.4.0)

fbird_gen_id — のエイリアス ibase_gen_id()

### 説明

この関数は次の関数のエイリアスです。 ibase_gen_id().

# fbird_maintain_db

(PHP 5, PHP 7 < 7.4.0)

fbird_maintain_db — のエイリアス ibase_maintain_db()

### 説明

この関数は次の関数のエイリアスです。 ibase_maintain_db().

# 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

# 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

# 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

# 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

# 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

# fbird_pconnect

(PHP 5, PHP 7 < 7.4.0)

fbird_pconnect — のエイリアス ibase_pconnect()

### 説明

この関数は次の関数のエイリアスです。 ibase_pconnect().

### 参考

- fbird_close() - のエイリアス ibase_close
- fbird_connect() - のエイリアス ibase_connect

# fbird_prepare

(PHP 5, PHP 7 < 7.4.0)

fbird_prepare — のエイリアス ibase_prepare()

### 説明

この関数は次の関数のエイリアスです。 ibase_prepare().

# 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

# fbird_restore

(PHP 5, PHP 7 < 7.4.0)

fbird_restore — のエイリアス ibase_restore()

### 説明

この関数は次の関数のエイリアスです。 ibase_restore().

# fbird_rollback

(PHP 5, PHP 7 < 7.4.0)

fbird_rollback — のエイリアス ibase_rollback()

### 説明

この関数は次の関数のエイリアスです。 ibase_rollback().

# fbird_rollback_ret

(PHP 5, PHP 7 < 7.4.0)

fbird_rollback_ret — のエイリアス ibase_rollback_ret()

### 説明

この関数は次の関数のエイリアスです。 ibase_rollback_ret().

# fbird_server_info

(PHP 5, PHP 7 < 7.4.0)

fbird_server_info — のエイリアス ibase_server_info()

### 説明

この関数は次の関数のエイリアスです。 ibase_server_info().

# fbird_service_attach

(PHP 5, PHP 7 < 7.4.0)

fbird_service_attach — のエイリアス ibase_service_attach()

### 説明

この関数は次の関数のエイリアスです。 ibase_service_attach().

# fbird_service_detach

(PHP 5, PHP 7 < 7.4.0)

fbird_service_detach — のエイリアス ibase_service_detach()

### 説明

この関数は次の関数のエイリアスです。 ibase_service_detach().

# 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

# fbird_trans

(PHP 5, PHP 7 < 7.4.0)

fbird_trans — のエイリアス ibase_trans()

### 説明

この関数は次の関数のエイリアスです。 ibase_trans().

# 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

# ibase_add_user

(PHP 5, PHP 7 < 7.4.0)

ibase_add_user — Add a user to a security database

### 説明

function 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_affected_rows

(PHP 5, PHP 7 < 7.4.0)

ibase_affected_rows — 直近のクエリで変更された行の数を返す

### 説明

function ibase_affected_rows(resource `$link_identifier` = ?): int

この関数は、`link_identifier` で指定された トランザクション内で実行された直近のクエリ(INSERT、UPDATE あるいは DELETE)によって変更された行の数を返します。

### パラメータ

`link_identifier`
  トランザクションのコンテキスト。 `link_identifier` が接続リソースの場合、 そのデフォルトのトランザクションが使用されます。

### 戻り値

変更された行数を整数値で返します。

### 参考

- ibase_query() - InterBase データベースでクエリを実行する
- ibase_execute() - 準備されたクエリを実行する

# ibase_backup

(PHP 5, PHP 7 < 7.4.0)

ibase_backup — Initiates a backup task in the service manager and returns immediately

### 説明

function 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

# ibase_blob_add

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_add — 生成された blob にデータを追加する

### 説明

function 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 を生成し、ファイルをコピーし、閉じる

# ibase_blob_cancel

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_cancel — blob の生成を取り消す

### 説明

function 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 を生成し、ファイルをコピーし、閉じる

# ibase_blob_close

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_close — blob を閉じる

### 説明

function 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 をオープンする

# ibase_blob_create

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_create — データを追加するために blob を生成する

### 説明

function 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 を生成し、ファイルをコピーし、閉じる

# ibase_blob_echo

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_echo — ブラウザに blob の内容を出力する

### 説明

function ibase_blob_echo(string `$blob_id`): bool
function 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 バイト分のデータを取得する

# ibase_blob_get

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_get — オープンした blob から len バイト分のデータを取得する

### 説明

function 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 の内容を出力する

# ibase_blob_import

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_import — blob を生成し、ファイルをコピーし、閉じる

### 説明

function ibase_blob_import(resource `$link_identifier`, resource `$file_handle`): string
function 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 を生成する

# ibase_blob_info

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_info — blob の長さと他の便利な情報を返す

### 説明

function ibase_blob_info(resource `$link_identifier`, string `$blob_id`): array
function ibase_blob_info(string `$blob_id`): array

BLOB の長さや他の便利な情報を返します。

### パラメータ

`link_identifier`
  InterBase リンク ID。省略した場合は、 最後にオープンしたリンクを使用します。
`blob_id`
  BLOB の ID。

### 戻り値

BLOB についての情報を含む配列を返します。返される情報には BLOB の長さ・含んでいるセグメントの数・最大のセグメントのサイズ・ ストリーム BLOB とセグメント BLOB のどちらであるかなどがあります。

# ibase_blob_open

(PHP 5, PHP 7 < 7.4.0)

ibase_blob_open — データの一部を取得するために blob をオープンする

### 説明

function ibase_blob_open(resource `$link_identifier`, string `$blob_id`): resource|false
function 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 バイト分のデータを取得する

# ibase_close

(PHP 5, PHP 7 < 7.4.0)

ibase_close — InterBase データベースへの接続を閉じる

### 説明

function 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_commit

(PHP 5, PHP 7 < 7.4.0)

ibase_commit — トランザクションをコミットする

### 説明

function ibase_commit(resource `$link_or_trans_identifier` = `null`): bool

トランザクションをコミットします。

### パラメータ

`link_or_trans_identifier`
  引数なしでコールされた場合、この関数はデフォルトリンクの デフォルトのトランザクションをコミットします。引数が接続 ID であった場合は、対応する接続のデフォルトのトランザクションを コミットします。引数がトランザクション ID であった場合は、 対応するトランザクションがコミットされます。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

# ibase_commit_ret

(PHP 5, PHP 7 < 7.4.0)

ibase_commit_ret — トランザクションを閉じずにコミットする

### 説明

function ibase_commit_ret(resource `$link_or_trans_identifier` = `null`): bool

トランザクションを閉じずにコミットします。

### パラメータ

`link_or_trans_identifier`
  引数なしでコールされた場合、この関数はデフォルトリンクのデフォルトの トランザクションをコミットします。引数が接続 ID だった場合、対応する 接続のデフォルトのトランザクションをコミットします。引数が トランザクション ID だった場合、対応するトランザクションをコミットします。 トランザクションコンテキストはそのまま維持され、このトランザクション内で 実行された文は取り消されません。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

# ibase_connect

(PHP 5, PHP 7 < 7.4.0)

ibase_connect — データベースへの接続をオープンする

### 説明

function 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_db_info

(PHP 5, PHP 7 < 7.4.0)

ibase_db_info — データベースについての統計情報を要求する

### 説明

function ibase_db_info(
resource `$service_handle`,
string `$db`,
int `$action`,
int `$argument` = 0
): string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

# ibase_delete_user

(PHP 5, PHP 7 < 7.4.0)

ibase_delete_user — Delete a user from a security database

### 説明

function 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_drop_db

(PHP 5, PHP 7 < 7.4.0)

ibase_drop_db — データベースを削除する

### 説明

function ibase_drop_db(resource `$connection` = `null`): bool

この関数は、ibase_connect() あるいは ibase_pconnect() のいずれかによってオープンされたデータベースを削除します。 データベースがクローズされ、サーバーから削除されます。

### パラメータ

`connection`
  InterBase リンク ID。省略した場合は、 最後にオープンしたリンクを使用します。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- ibase_connect() - データベースへの接続をオープンする
- ibase_pconnect() - InterBase データベースへの持続的接続をオープンする

# ibase_errcode

(PHP 5, PHP 7 < 7.4.0)

ibase_errcode — エラーコードを返す

### 説明

function ibase_errcode(): int

直近の InterBase 関数のコールによって得られたエラーコードを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

エラーコードを表す整数、あるいはエラーが発生しなかった場合は `false` を返します。

### 参考

- ibase_errmsg() - エラーメッセージを返す

# ibase_errmsg

(PHP 5, PHP 7 < 7.4.0)

ibase_errmsg — エラーメッセージを返す

### 説明

function ibase_errmsg(): string

直近の InterBase 関数コールの結果として得られるエラーメッセージを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

エラーメッセージを表す文字列、あるいはエラーが発生しなかった場合は `false` を返します。

### 参考

- ibase_errcode() - エラーコードを返す

# ibase_execute

(PHP 5, PHP 7 < 7.4.0)

ibase_execute — 準備されたクエリを実行する

### 説明

function 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_fetch_assoc

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_assoc — クエリの結果から、行を連想配列として取得する

### 説明

function 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 データベースからオブジェクトを得る

# ibase_fetch_object

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_object — InterBase データベースからオブジェクトを得る

### 説明

function 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() - クエリの結果から、行を連想配列として取得する

# ibase_fetch_row

(PHP 5, PHP 7 < 7.4.0)

ibase_fetch_row — InterBase データベースから 1 行分の結果を取得する

### 説明

function 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_field_info

(PHP 5, PHP 7 < 7.4.0)

ibase_field_info — フィールドに関する情報を得る

### 説明

function 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_free_event_handler

(PHP 5, PHP 7 < 7.4.0)

ibase_free_event_handler — 登録済みのイベントハンドラをキャンセルする

### 説明

function ibase_free_event_handler(resource `$event`): bool

この関数は、`event` で指定した登録済みの イベントハンドラをキャンセルします。イベントに対応して登録されていた コールバック関数は、もはやコールされません。

### パラメータ

`event`
  ibase_set_event_handler() で作成したイベントリソース。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- ibase_set_event_handler() - イベントが発生した際にコールされるコールバック関数を登録する

# ibase_free_query

(PHP 5, PHP 7 < 7.4.0)

ibase_free_query — プリペアドクエリにより確保されたメモリを解放する

### 説明

function ibase_free_query(resource `$query`): bool

プリペアドクエリを解放します。

### パラメータ

`query`
  ibase_prepare() で準備したクエリ。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

# ibase_free_result

(PHP 5, PHP 7 < 7.4.0)

ibase_free_result — 結果セットを解放する

### 説明

function ibase_free_result(resource `$result_identifier`): bool

結果セットを解放します。

### パラメータ

`result_identifier`
  ibase_query() あるいは ibase_execute() で作成した結果セット。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

# ibase_gen_id

(PHP 5, PHP 7 < 7.4.0)

ibase_gen_id — 指定した名前のジェネレータをひとつ加算し、その新しい値を返す

### 説明

function ibase_gen_id(string `$generator`, int `$increment` = 1, resource `$link_identifier` = `null`): mixed
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### 戻り値

新しいジェネレータの値を整数で返します。値が大きくなりすぎた場合は文字列で返します。

# ibase_maintain_db

(PHP 5, PHP 7 < 7.4.0)

ibase_maintain_db — データベースサーバーでメンテナンスコマンドを実行する

### 説明

function ibase_maintain_db(
resource `$service_handle`,
string `$db`,
int `$action`,
int `$argument` = 0
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

# ibase_modify_user

(PHP 5, PHP 7 < 7.4.0)

ibase_modify_user — Modify a user to a security database

### 説明

function 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_name_result

(PHP 5, PHP 7 < 7.4.0)

ibase_name_result — 結果セットに名前を割り当てる

### 説明

function 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_num_fields

(PHP 5, PHP 7 < 7.4.0)

ibase_num_fields — 結果セットにおけるフィールド数を得る

### 説明

function 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_params

(PHP 5, PHP 7 < 7.4.0)

ibase_num_params — プリペアドクエリのパラメータ数を返す

### 説明

function 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_param_info

(PHP 5, PHP 7 < 7.4.0)

ibase_param_info — プリペアドクエリのパラメータに関する情報を返す

### 説明

function ibase_param_info(resource `$query`, int `$param_number`): array

クエリが準備された後に、パラメータについての情報を配列で返します。

### パラメータ

`query`
  InterBase プリペアドクエリのハンドル。
`param_number`
  パラメータのオフセット。

### 戻り値

配列を返します。配列に含まれるキーは `name`、 `alias`、`relation`、 `length` および `type` となります。

### 参考

- ibase_field_info() - フィールドに関する情報を得る
- ibase_num_params() - プリペアドクエリのパラメータ数を返す

# ibase_pconnect

(PHP 5, PHP 7 < 7.4.0)

ibase_pconnect — InterBase データベースへの持続的接続をオープンする

### 説明

function 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() - データベースへの接続をオープンする

# ibase_prepare

(PHP 5, PHP 7 < 7.4.0)

ibase_prepare — Prepare a query for later binding of parameter placeholders and execution

### 説明

function ibase_prepare(string `$query`): resource
function ibase_prepare(resource `$link_identifier`, string `$query`): resource
function 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.

# ibase_query

(PHP 5, PHP 7 < 7.4.0)

ibase_query — InterBase データベースでクエリを実行する

### 説明

function 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() - 結果セットを解放する

# ibase_restore

(PHP 5, PHP 7 < 7.4.0)

ibase_restore — Initiates a restore task in the service manager and returns immediately

### 説明

function 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_rollback

(PHP 5, PHP 7 < 7.4.0)

ibase_rollback — トランザクションをロールバックする

### 説明

function ibase_rollback(resource `$link_or_trans_identifier` = `null`): bool

トランザクションをロールバックします。

### パラメータ

`link_or_trans_identifier`
  引数なしでコールされた場合、この関数はデフォルトリンクのデフォルトの トランザクションをロールバックします。引数として接続 ID が渡された場合、 対応する接続のデフォルトのトランザクションをロールバックします。 引数としてトランザクション ID が渡された場合、対応するトランザクションを ロールバックします。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

# ibase_rollback_ret

(PHP 5, PHP 7 < 7.4.0)

ibase_rollback_ret — トランザクションを閉じずにロールバックする

### 説明

function ibase_rollback_ret(resource `$link_or_trans_identifier` = `null`): bool

トランザクションを閉じずにロールバックします。

### パラメータ

`link_or_trans_identifier`
  引数なしでコールされた場合、この関数はデフォルトリンクのデフォルトの トランザクションをロールバックします。引数が接続 ID だった場合、対応する 接続のデフォルトのトランザクションをロールバックします。引数が トランザクション ID だった場合、対応するトランザクションをロールバックします。 トランザクションコンテキストはそのまま維持され、このトランザクション内で 実行された文は取り消されません。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

# ibase_server_info

(PHP 5, PHP 7 < 7.4.0)

ibase_server_info — データベースサーバーについての情報を要求する

### 説明

function 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_service_attach

(PHP 5, PHP 7 < 7.4.0)

ibase_service_attach — サービスマネージャに接続する

### 説明

function 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_detach

(PHP 5, PHP 7 < 7.4.0)

ibase_service_detach — サービスマネージャとの接続を切断する

### 説明

function 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_set_event_handler

(PHP 5, PHP 7 < 7.4.0)

ibase_set_event_handler — イベントが発生した際にコールされるコールバック関数を登録する

### 説明

function ibase_set_event_handler(callable `$event_handler`, string `$event_name`, string `...$even_names`): resource
function 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_trans

(PHP 5, PHP 7 < 7.4.0)

ibase_trans — トランザクションを開始する

### 説明

function ibase_trans(int `$trans_args` = ?, resource `$link_identifier` = ?): resource
function ibase_trans(resource `$link_identifier` = ?): 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_wait_event

(PHP 5, PHP 7 < 7.4.0)

ibase_wait_event — データベースでイベントが発生するのを待つ

### 説明

function ibase_wait_event(string `$event_name`, string `...$event_names`): string
function 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() - 登録済みのイベントハンドラをキャンセルする

## 目次

- 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 — データベースでイベントが発生するのを待つ

- インストール/設定
  - インストール手順
  - 実行時設定
- 定義済み定数
- 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 — データベースでイベントが発生するのを待つ

# IBM DB2、Cloudscape および Apache Derby

# はじめに

これらの関数により、DB2 Call Level Interface (DB2 CLI) を使用した IBM DB2 Universal Database、IBM Cloudscape および Apache Derby データベースへのアクセスが可能となります。

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定
- リソース型

## 要件

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

  このオプションは、IBM i における内部バッファの割当て戦略に影響します。 デフォルトでは、このオプションの値は `0` です。 このオプションを設定した場合、 エンコーディング変換時にデータベースが文字列サイズを過小評価した場合に備えて、 さらに大きなサイズのバッファが割り当てられます。 このオプションはバッファ用に6倍のメモリを使用します（最大サイズのUTF-8シーケンスに対応するため）。 切り詰められたデータが返される場合に必要となる可能性があります。

  - 0 - 最低限のバッファサイズが割り当てられます
  - 1 - さらに大きなバッファサイズを割り当てます
`ibm_db2.i5_guard_profile` int

  IBM i 上のデータベースに持続的接続する際、 ユーザーのデータベースのプロファイルを切り替えるかどうかをチェックします。 切り替える場合、データベースから切断します。 デフォルトでは、このオプションの値は `0` です。

  - 0 - プロファイルの切換をチェックしません
  - 1 - プロファイルの切換をチェックし、切り替える場合は切断します
`ibm_db2.i5_log_verbose` int

  このオプションは、 IBM i 上で 警告やエラーなどのSQL診断メッセージを、 常に PHP のエラーログに送信するかどうかを設定します。 通常、このオプションはデフォルトで `0` に設定されているため、 失敗時には簡潔なメッセージ（例：「ステートメントの実行に失敗しました」）のみが PHP のエラーログに送信されます。 ただし、関数が失敗したかどうかを確認する目的で db2_stmt_errormsg() を手動で呼び出すことができますし、 またそうすべきである点に注意してください。

  - 0 - 簡潔なメッセージだけをログに残します
  - 1 - 簡潔なメッセージに加えて、SQL診断メッセージをログに残します
`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
  IBM i 上の EBCDIC から文字変換に使用する PASE CCSID。 デフォルトでこの値は `0` であり、 PASE ロケール設定から取得されるデフォルトの PASE ジョブ CCSID を選択します。 たとえば、これを `1208` に設定すると UTF-8 を使用します。 この値は、PASE ジョブの CCSID が期待される CCSID と異なる場合、 かつロケールを変更できない場合にのみ変更してください。 IBM i 上の CCSID についてさらに学ぶ場合は、 » IBM documentation を調べてください。 IBM i 上の PASE がどのように CCSID にマップされているかについては、 » IBM documentation を調べてください。
`ibm_db2.i5_sys_naming` int

  このオプションは、IBM i システムに接続する際の命名モードを制御します。 デフォルトでは、このオプションの値は `0` です。 命名モードは、名前の解決方法と名前に許可される構文に影響します。 `0` に設定すると、名前の修飾にピリオドを使用し、 名前解決にはデフォルトのライブラリまたはユーザーIDを使用します。 `1` に設定すると、名前の修飾にスラッシュを使用し、 名前解決にはジョブライブラリリストを使用します。

  - 0 - SQL の命名モードを使う("SCHEMA.TABLE").
  - 1 - システムの命名モードを使う("LIBRARY/FILE").
  IBM i 上の命名モードについて学ぶには、 » IBM documentation を調べてください。
`ibm_db2.i5_servermode-subsystem` string
  このオプションは、 IBM i 上でどのサブシステムデータベースサーバージョブが実行されるかを変更します。 デフォルトでは、このオプションは `null` であるため、 ジョブは QSQSRVR ジョブのデフォルトサブシステムで実行されます。
`ibm_db2.instance_name` string

  Linux や UNIX オペレーティングシステムにおいて、 このオプションはカタログされたデータベースへの接続で使う、 インスタンス名を定義します。 デフォルトでは、このオプションの値は `null` です。 このオプションを設定すると、 環境変数 DB2INSTANCE の値を上書きします。

  Windows では、このオプションの値は無視されます。

## リソース型

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

(PECL ibm_db2 >= 1.0.0)

db2_autocommit — データベース接続の AUTOCOMMIT の状態を取得または設定する

### 説明

function 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() - データベースへの持続的接続を返す

# db2_bind_param

(PECL ibm_db2 >= 1.0.0)

db2_bind_param — PHP 変数を SQL 文のパラメータにバインドする

### 説明

function 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_client_info

(PECL ibm_db2 >= 1.1.1)

db2_client_info — DB2 データベースクライアントの情報をプロパティに保持するオブジェクトを返す

### 説明

function 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_close

(PECL ibm_db2 >= 1.0.0)

db2_close — データベース接続を閉じる

### 説明

function 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_column_privileges

(PECL ibm_db2 >= 1.0.0)

db2_column_privileges — テーブルのカラムおよび関連する権限情報を含む結果セットを返す

### 説明

function 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_columns

(PECL ibm_db2 >= 1.0.0)

db2_columns — テーブルのカラムおよび関連するメタデータを含む結果セットを返す

### 説明

function 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_commit

(PECL ibm_db2 >= 1.0.0)

db2_commit — トランザクションをコミットする

### 説明

function db2_commit(resource `$connection`): bool

指定した接続リソース上で実行中のトランザクションをコミットし、 新しいトランザクションを開始します。PHP アプリケーションのデフォルトは AUTOCOMMIT モードなので、接続リソースに対して AUTOCOMMIT を無効にしていない限り db2_commit() は必要ありません。

### パラメータ

`connection`
  db2_connect() あるいは db2_pconnect() が返した有効なデータベース接続リソース。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- db2_autocommit() - データベース接続の AUTOCOMMIT の状態を取得または設定する
- db2_rollback() - トランザクションをロールバックする

# db2_conn_error

(PECL ibm_db2 >= 1.0.0)

db2_conn_error — 直近の接続から返された SQLSTATE を含む文字列を返す

### 説明

function 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 文のエラーメッセージを含む文字列を返す

# db2_conn_errormsg

(PECL ibm_db2 >= 1.0.0)

db2_conn_errormsg — 直近の接続エラーメッセージおよび SQLCODE を返す

### 説明

function 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_connect

(PECL ibm_db2 >= 1.0.0)

db2_connect — データベースへの接続を返す

### 説明

function 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_cursor_type

(PECL ibm_db2 >= 1.0.0)

db2_cursor_type — ステートメントリソースが使用しているカーソルの型を返す

### 説明

function db2_cursor_type(resource `$stmt`): int

ステートメントリソースが使用しているカーソルの型を返します。 使用中のカーソルが前進のみなのかスクロール可能なのかを調べるために、 これを使用します。

### パラメータ

`stmt`
  有効なステートメントリソース。

### 戻り値

ステートメントリソースが前進のみのカーソルを使用している場合に `DB2_FORWARD_ONLY`、スクロール可能なカーソルを 使用している場合に `DB2_SCROLLABLE` を返します。

### 参考

- db2_prepare() - 実行する SQL 文を準備する

# db2_escape_string

(PECL ibm_db2 >= 1.6.0)

db2_escape_string — 特定の文字をエスケープする

### 説明

function 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 文を準備する

# db2_exec

(PECL ibm_db2 >= 1.0.0)

db2_exec — SQL 文を直接実行する

### 説明

function 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_execute

(PECL ibm_db2 >= 1.0.0)

db2_execute — プリペアドステートメントを実行する

### 説明

function 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_fetch_array

(PECL ibm_db2 >= 1.0.1)

db2_fetch_array — 結果セット内の行を表す、カラム位置をインデックスとする配列を返す

### 説明

function 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_assoc

(PECL ibm_db2 >= 1.0.0)

db2_fetch_assoc — 結果セット内の行を表す、カラム名をインデックスとする配列を返す

### 説明

function 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_both

(PECL ibm_db2 >= 1.0.0)

db2_fetch_both — 結果セット内の行を表す、 カラム位置およびカラム名の両方をインデックスとする配列を返す

### 説明

function 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_object

(PECL ibm_db2 >= 1.0.0)

db2_fetch_object — 結果セット内の行を表す、カラムをプロパティとするオブジェクトを返す

### 説明

function 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_row

(PECL ibm_db2 >= 1.0.0)

db2_fetch_row — 結果セットポインタを次の行あるいは要求された行に設定する

### 説明

function 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() は、さまざまなカラム型で `EBCDIC` から `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_field_display_size

(PECL ibm_db2 >= 1.0.0)

db2_field_display_size — カラムを表示するために必要な最大のバイト数を返す

### 説明

function 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_name

(PECL ibm_db2 >= 1.0.0)

db2_field_name — 結果セット内のカラムの名前を返す

### 説明

function 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_num

(PECL ibm_db2 >= 1.0.0)

db2_field_num — 結果セット内の指定したカラムの位置を返す

### 説明

function 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_precision

(PECL ibm_db2 >= 1.0.0)

db2_field_precision — 結果セット内の指定したカラムの精度を返す

### 説明

function 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_scale

(PECL ibm_db2 >= 1.0.0)

db2_field_scale — 結果セット内の指定したカラムの位取りを返す

### 説明

function 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_type

(PECL ibm_db2 >= 1.0.0)

db2_field_type — 結果セット内の指定したカラムのデータ型を返す

### 説明

function 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_width

(PECL ibm_db2 >= 1.0.0)

db2_field_width — 結果セット内の指定したカラムの現在値の幅を返す

### 説明

function 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_foreign_keys

(PECL ibm_db2 >= 1.0.0)

db2_foreign_keys — テーブルの外部キーを含む結果セットを返す

### 説明

function 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_free_result

(PECL ibm_db2 >= 1.0.0)

db2_free_result — 結果セットに関連付けられたリソースを開放する

### 説明

function db2_free_result(resource `$stmt`): bool

結果セットに関連付けられたシステムリソースおよびデータベースリソースを 開放します。これらのリソースはスクリプトの終了時に暗黙的に開放されますが、 スクリプトの終了前に db2_free_result() をコールすることで、明示的に結果セットリソースを開放することができます。

### パラメータ

`stmt`
  有効なステートメントリソース。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- db2_free_stmt() - 指定されたステートメントリソースに関連付けられたリソースを開放する

# db2_free_stmt

(PECL ibm_db2 >= 1.0.0)

db2_free_stmt — 指定されたステートメントリソースに関連付けられたリソースを開放する

### 説明

function db2_free_stmt(resource `$stmt`): bool

ステートメントリソースに関連付けられたシステムリソースおよびデータベースリソースを 開放します。これらのリソースはスクリプトの終了時に暗黙的に開放されますが、 スクリプトの終了前に db2_stmt_result() をコールすることで、明示的にステートメントリソースを開放することができます。

### パラメータ

`stmt`
  有効なステートメントリソース。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- db2_free_result() - 結果セットに関連付けられたリソースを開放する

# db2_get_option

(PECL ibm_db2 >= 1.6.0)

db2_get_option — ステートメントリソースあるいは接続リソースからオプションの値を取得する

### 説明

function 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 文を準備する

# db2_last_insert_id

(PECL ibm_db2 >= 1.7.1)

db2_last_insert_id — この接続上で最後に成功した insert クエリが自動生成した ID を返す

### 説明

function 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

# db2_lob_read

(PECL ibm_db2 >= 1.6.0)

db2_lob_read — LOB ファイルから、ユーザーが定義したサイズの内容を取得する

### 説明

function 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_next_result

(PECL ibm_db2 >= 1.0.0)

db2_next_result — ストアドプロシージャから、次の結果セットを要求する

### 説明

function 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_num_fields

(PECL ibm_db2 >= 1.0.0)

db2_num_fields — 結果セットに含まれるフィールドの数を返す

### 説明

function 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() - 結果セット内の指定したカラムの現在値の幅を返す

# db2_num_rows

(PECL ibm_db2 >= 1.0.0)

db2_num_rows — SQL 文によって変更された行の数を返す

### 説明

function 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_pclose

(PECL ibm_db2 >= 1.8.0)

db2_pclose — 持続的データベース接続を閉じる

### 説明

function 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_pconnect

(PECL ibm_db2 >= 1.0.0)

db2_pconnect — データベースへの持続的接続を返す

### 説明

function 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` を返します。

### 変更履歴

バージョン | 説明
--- | ---
PECL ibm_db2 1.9.0 | 持続的接続上のアクティブなトランザクションは、各接続の終了時にロールバックされるようになりました。
PECL ibm_db2 1.8.0 | i5/OS ユーザーは `i5_libl` オプションが使えるようになりました。
PECL ibm_db2 1.7.0 | `trustedcontext` オプションが使えるようになりました。
PECL 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() - データベースへの接続を返す

# db2_prepare

(PECL ibm_db2 >= 1.0.0)

db2_prepare — 実行する SQL 文を準備する

### 説明

function 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_primary_keys

(PECL ibm_db2 >= 1.0.0)

db2_primary_keys — テーブルの主キーを含む結果セットを返す

### 説明

function 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_procedure_columns

(PECL ibm_db2 >= 1.0.0)

db2_procedure_columns — ストアドプロシージャのパラメータを含む結果セットを返す

### 説明

function 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_procedures

(PECL ibm_db2 >= 1.0.0)

db2_procedures — データベース内に登録されているストアドプロシージャの一覧を含む結果セットを返す

### 説明

function 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_result

(PECL ibm_db2 >= 1.0.0)

db2_result — 結果セットの行からひとつのカラムを返す

### 説明

function 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_rollback

(PECL ibm_db2 >= 1.0.0)

db2_rollback — トランザクションをロールバックする

### 説明

function 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_server_info

(PECL ibm_db2 >= 1.1.1)

db2_server_info — DB2 データベースサーバーの情報をプロパティに保持するオブジェクトを返す

### 説明

function 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_set_option

(PECL ibm_db2 >= 1.0.0)

db2_set_option — 接続リソースあるいはステートメントリソースのオプションを設定する

### 説明

function 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() - ステートメントリソースが使用しているカーソルの型を返す

# db2_special_columns

(PECL ibm_db2 >= 1.0.0)

db2_special_columns — テーブルのユニーク行 ID カラムを含む結果セットを返す

### 説明

function 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_statistics

(PECL ibm_db2 >= 1.0.0)

db2_statistics — インデックスの情報およびテーブルの統計情報を含む結果セットを返す

### 説明

function 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() - データベース内のテーブルおよび関連するメタデータを含む結果セットを返す

# db2_stmt_error

(PECL ibm_db2 >= 1.0.0)

db2_stmt_error — SQL 文が返す SQLSTATE を含む文字列を返す

### 説明

function 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 文のエラーメッセージを含む文字列を返す

# db2_stmt_errormsg

(PECL ibm_db2 >= 1.0.0)

db2_stmt_errormsg — 直近の SQL 文のエラーメッセージを含む文字列を返す

### 説明

function 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_table_privileges

(PECL ibm_db2 >= 1.0.0)

db2_table_privileges — データベース内のテーブルおよび関連する権限情報を含む結果セットを返す

### 説明

function 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_tables

(PECL ibm_db2 >= 1.0.0)

db2_tables — データベース内のテーブルおよび関連するメタデータを含む結果セットを返す

### 説明

function 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() - データベース内のテーブルおよび関連する権限情報を含む結果セットを返す

## 目次

- 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 — データベース内のテーブルおよび関連するメタデータを含む結果セットを返す

- インストール/設定
  - 要件
  - インストール手順
  - 実行時設定
  - リソース型
- 定義済み定数
- 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 — データベース内のテーブルおよび関連するメタデータを含む結果セットを返す

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

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定

## 要件

As of version 1.21.0, the extension requires PHP 8.1 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 PIE

> 注意: PHP Installer for Extensions (PIE) は、PECL を非推奨にする新しいツールです。 拡張モジュールをインストールする用途には、PIE を推奨します。 詳しい情報は、 » https://github.com/php/pie を参照ください。

To install the MongoDB extension using PIE, run the following command:

    pie install mongodb/mongodb-extension

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

Alternatively, the » shivammathur/extensions tap provides formulae for individual PHP extensions. For example, to install the extension for PHP 8.4, run:

    $ brew install shivammathur/extensions/mongodb@8.4

Please note that only the latest extension version is available in brew.

> 注意: Install required dependencies
> To ensure that SSL support can be configured correctly, make sure that the `openssl` and `pkgconf` formulae are installed. If either of these packages are missing, the extension will be compiled with Secure Transport, which can lead to compatibility issues.

## 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`.

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

## 目次

- Using the PHP Library for MongoDB (PHPLIB)
- Application Performance Monitoring (APM)

In this section you will find several tutorials on how to use the MongoDB driver for PHP.

## 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
- Connections
- Persisting Data

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

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]

    A __pclass property is only deemed to exist if there exists a property with that name, and it is a Binary value, and the sub-type of the Binary value is 0x80. If any of these three conditions is not met, the __pclass property does not exist and should be treated as any other normal property.

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

# 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
- MongoDB\Driver\Command
- MongoDB\Driver\Query
- MongoDB\Driver\BulkWrite
- MongoDB\Driver\BulkWriteCommand
- MongoDB\Driver\Session
- MongoDB\Driver\ClientEncryption
- MongoDB\Driver\ServerApi
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\ReadPreference
- MongoDB\Driver\ReadConcern
- MongoDB\Driver\Cursor
- MongoDB\Driver\CursorId
- MongoDB\Driver\CursorInterface
- MongoDB\Driver\Server
- MongoDB\Driver\ServerDescription
- MongoDB\Driver\TopologyDescription
- MongoDB\Driver\WriteConcernError
- MongoDB\Driver\WriteError
- MongoDB\Driver\WriteResult
- MongoDB\Driver\BulkWriteCommandResult

# 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 function addSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void
final public function __construct(?string `$uri` = `null`, ?array `$uriOptions` = `null`, ?array `$driverOptions` = `null`)
final public function createClientEncryption(array `$options`): MongoDB\Driver\ClientEncryption
final public function executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$options` = `null`): MongoDB\Driver\WriteResult
final public function executeBulkWriteCommand(MongoDB\Driver\BulkWriteCommand `$bulk`, ?array `$options` = `null`): MongoDB\Driver\BulkWriteCommandResult
final public function executeCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeQuery(string `$namespace`, MongoDB\Driver\Query `$query`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeReadCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeReadWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function getEncryptedFieldsMap(): array|object|null
final public function getReadConcern(): MongoDB\Driver\ReadConcern
final public function getReadPreference(): MongoDB\Driver\ReadPreference
final public function getServers(): array
final public function getWriteConcern(): MongoDB\Driver\WriteConcern
final public function removeSubscriber(MongoDB\Driver\Monitoring\Subscriber `$subscriber`): void
final public function selectServer(?MongoDB\Driver\ReadPreference `$readPreference` = `null`): MongoDB\Driver\Server
final public function 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

(mongodb >=1.10.0)

MongoDB\Driver\Manager::addSubscriber — Registers a monitoring event subscriber with this Manager

### 説明

final public function 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)

# MongoDB\Driver\Manager::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Manager::__construct — Create new MongoDB Manager

### 説明

final public function 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]]

  Defaults to `"mongodb://127.0.0.1:27017"` if unspecified. 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"`.
  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).
  enableOverloadRetargeting | bool | When set to `true` it forces server selection after a `SystemOverloadedError`. Defaults to `false`.
  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.
  maxAdaptiveRetries | int | This option can be used to change the maximum number of retries when a `SystemOverloadedError` occurs. Must be a positive integer; defaults to `2`.
  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.
  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"`.
  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
  --- | --- | ---
  autoEncryption | array | Provides options to enable automatic client-side field level encryption. The list of options is described in the table below. 注意: 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`.
  ca_dir | string | Path to a correctly hashed certificate directory. The system certificate store will be used by default.
  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.
  serverApi | MongoDB\Driver\ServerApi | This option is used to declare a server API version for the manager. If omitted, no API version is declared.

  Options supported by automatic encryption through the `autoEncryption` driver option:

  autoEncryption
  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. This option is required.
  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.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\RuntimeException if the `uri` format is invalid

### 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | The `"canonicalizeHostname"` URI option was removed. Use the `"CANONICALIZE_HOST_NAME"` property of the `"authMechanismProperties"` URI option instead. The `"gssapiServiceName"` URI option was removed. Use the `"SERVICE_NAME"` property of the `"authMechanismProperties"` URI option instead. The `"safe"` URI option was removed. Use the `"w"` and `"wTimeoutMS"` URI options instead. The `"ssl"` URI option was removed. Use the `"tls"` URI option instead. The `"allow_invalid_hostname"` driver option was removed. Use the `"tlsAllowInvalidHostnames"` URI option instead. The `"ca_file"` driver option was removed. Use the `"tlsCAFile"` URI option instead. The `"context"` driver option was removed. All context options were deprecated in favor of the various URI options related to TLS. The `"pem_file"` driver option was removed. Use the `"tlsCertificateKeyFile"` URI option instead. The `"pem_pwd"` driver option was removed. Use the `"tlsCertificateKeyFilePassword"` URI option instead. The `"weak_cert_validation"` driver option was removed. Use the `"tlsAllowInvalidCertificates"` URI option instead.
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

# MongoDB\Driver\Manager::createClientEncryption

(mongodb >=1.7.0)

MongoDB\Driver\Manager::createClientEncryption — Create a new ClientEncryption object

### 説明

final public function 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. This option is required.
  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

# MongoDB\Driver\Manager::executeBulkWrite

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeBulkWrite — Execute one or more write operations

### 説明

final public function MongoDB\Driver\Manager::executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$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 2.0.0 | The `options` parameter no longer accepts a MongoDB\Driver\WriteConcern instance.
PECL mongodb 1.21.0 | Passing a MongoDB\Driver\WriteConcern object as `options` is deprecated and will be removed in 2.0.
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' => $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

# MongoDB\Driver\Manager::executeBulkWriteCommand

(mongodb >=2.1.0)

MongoDB\Driver\Manager::executeBulkWriteCommand — Execute write operations using the bulkWrite command

### 説明

final public function MongoDB\Driver\Manager::executeBulkWriteCommand(MongoDB\Driver\BulkWriteCommand `$bulk`, ?array `$options` = `null`): MongoDB\Driver\BulkWriteCommandResult

Executes one or more write operations on the primary server using the » bulkWrite command introduced in MongoDB 8.0.

A MongoDB\Driver\BulkWriteCommand can be constructed with one or more write operations of varying types (e.g. inserts, updates, and deletes). Each write operation may target a different collection.

The default value for the `"writeConcern"` option will be inferred from an active transaction (indicated by the `"session"` option), followed by the connection URI.

### パラメータ

`bulk` (MongoDB\Driver\BulkWriteCommand)
  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\BulkWriteCommandResult 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\BulkWriteCommand 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\BulkWriteCommandException on any write failure (e.g. command failure, write or write concern error)
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

### 例

例1 Mixed write operations

Mixed write operations (i.e. inserts, updates, and deletes) will be sent to the server using a single » bulkWrite command.

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    // Delete documents from both collections
    $bulk->deleteMany('db.coll_one', []);
    $bulk->deleteMany('db.coll_two', []);

    // Insert documents into two collections
    $bulk->insertOne('db.coll_one', ['_id' => 1]);
    $bulk->insertOne('db.coll_two', ['_id' => 2]);
    $bulk->insertOne('db.coll_two', ['_id' => 3]);

    // Update a document in "coll_one"
    $bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    printf("Inserted %d document(s)\n", $result->getInsertedCount());
    printf("Updated  %d document(s)\n", $result->getModifiedCount());

    ?>

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

    Inserted 3 document(s)
    Updated  1 document(s)

例2 Ordered write operations causing an error

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 2]);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 3]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        $result = $e->getPartialResult();

        var_dump($e->getWriteErrors());
    }

    printf("Inserted %d document(s)\n", $result->getInsertedCount());

    ?>

上の例の出力は、 たとえば以下のようになります。

    array(1) {
      [3]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(3)
        ["info"]=>
        object(stdClass)#6 (0) {
        }
      }
    }
    Inserted 2 document(s)

### 参考

- MongoDB\Driver\BulkWriteCommand
- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Server::executeBulkWriteCommand() - Execute write operations on this server using the bulkWrite command

# MongoDB\Driver\Manager::executeCommand

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeCommand — Execute a database command

### 説明

final public function MongoDB\Driver\Manager::executeCommand(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 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 2.0.0 | The `options` parameter no longer accepts a MongoDB\Driver\ReadPreference instance.
PECL mongodb 1.21.0 | Passing a MongoDB\Driver\ReadPreference object as `options` is deprecated and will be removed in 2.0.
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

# MongoDB\Driver\Manager::executeQuery

(mongodb >=1.0.0)

MongoDB\Driver\Manager::executeQuery — Execute a database query

### 説明

final public function MongoDB\Driver\Manager::executeQuery(string `$namespace`, MongoDB\Driver\Query `$query`, ?array `$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 2.0.0 | The `options` parameter no longer accepts a MongoDB\Driver\ReadPreference instance.
PECL mongodb 1.21.0 | Passing a MongoDB\Driver\ReadPreference object as `options` is deprecated and will be removed in 2.0.
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

# MongoDB\Driver\Manager::executeReadCommand

(mongodb >=1.4.0)

MongoDB\Driver\Manager::executeReadCommand — Execute a database command that reads

### 説明

final public function 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

# MongoDB\Driver\Manager::executeReadWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Manager::executeReadWriteCommand — Execute a database command that reads and writes

### 説明

final public function 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

# MongoDB\Driver\Manager::executeWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Manager::executeWriteCommand — Execute a database command that writes

### 説明

final public function 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

# MongoDB\Driver\Manager::getEncryptedFieldsMap

(mongodb >=1.14.0)

MongoDB\Driver\Manager::getEncryptedFieldsMap — Return the encryptedFieldsMap auto encryption option for the Manager

### 説明

final public function 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

# MongoDB\Driver\Manager::getReadConcern

(mongodb >=1.1.0)

MongoDB\Driver\Manager::getReadConcern — Return the ReadConcern for the Manager

### 説明

final public function 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

# MongoDB\Driver\Manager::getReadPreference

(mongodb >=1.0.0)

MongoDB\Driver\Manager::getReadPreference — Return the ReadPreference for the Manager

### 説明

final public function 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

# MongoDB\Driver\Manager::getServers

(mongodb >=1.0.0)

MongoDB\Driver\Manager::getServers — Return the servers to which this manager is connected

### 説明

final public function 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

# MongoDB\Driver\Manager::getWriteConcern

(mongodb >=1.0.0)

MongoDB\Driver\Manager::getWriteConcern — Return the WriteConcern for the Manager

### 説明

final public function 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

# MongoDB\Driver\Manager::removeSubscriber

(mongodb >=1.10.0)

MongoDB\Driver\Manager::removeSubscriber — Unregisters a monitoring event subscriber with this Manager

### 説明

final public function 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)

# MongoDB\Driver\Manager::selectServer

(mongodb >=1.0.0)

MongoDB\Driver\Manager::selectServer — Select a server matching a read preference

### 説明

final public function 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

# MongoDB\Driver\Manager::startSession

(mongodb >=1.4.0)

MongoDB\Driver\Manager::startSession — Start a new client session for use with this client

### 説明

final public function 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 » Causal 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
- » Causal Consistency in the MongoDB manual

## 目次

- 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::executeBulkWriteCommand — Execute write operations using the bulkWrite command
- 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

# 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 function __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

(mongodb >=1.0.0)

MongoDB\Driver\Command::__construct — Create a new Command

### 説明

final public function 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

## 目次

- MongoDB\Driver\Command::__construct — Create a new Command

# 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 function __construct(array|object `$filter`, ?array `$queryOptions` = `null`)
}

# MongoDB\Driver\Query::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Query::__construct — Create a new Query

### 説明

final public function 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.
  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.
  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.
  noCursorTimeout | bool | Prevents the server from timing out idle cursors after an inactivity period (10 minutes).
  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.
  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 2.0.0 | The `"partial"` option was removed. Use the `"allowPartialResults"` option instead. The `"maxScan"` option was removed. Support for this option was removed in MongoDB 4.2. The `"modifiers"` option was removed. This option was used for legacy query modifiers, which are all deprecated. The `"oplogReplay"` option was removed. It is ignored in MongoDB 4.4 and newer. The `"snapshot"` option was removed. Support for this option was removed in MongoDB 4.0. A negative value for the `"limit"` option no longer implies `true` for the `"singleBatch"` option. To only receive a single batch of results, combine a positive `"limit"` value with the `"singleBatch"` option.
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::PRIMARY);
    $cursor = $manager->executeQuery('databaseName.collectionName', $query, ['readPreference' => $readPreference]);

    foreach($cursor as $document) {
        var_dump($document);
    }

    ?>

### 参考

- MongoDB\Driver\Manager::executeQuery() - Execute a database query
- MongoDB\Driver\Cursor

## 目次

- MongoDB\Driver\Query::__construct — Create a new Query

# 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 function __construct(?array `$options` = `null`)
public function count(): int
public function delete(array|object `$filter`, ?array `$deleteOptions` = `null`): void
public function insert(array|object `$document`): mixed
public function 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' => $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

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::__construct — Create a new BulkWrite

### 説明

public function 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' => $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

# MongoDB\Driver\BulkWrite::count

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::count — Count number of write operations in the bulk

### 説明

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

# MongoDB\Driver\BulkWrite::delete

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::delete — Add a delete operation to the bulk

### 説明

public function 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

# MongoDB\Driver\BulkWrite::insert

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::insert — Add an insert operation to the bulk

### 説明

public function 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;

    $doc1 = ['x' => 1];
    $doc2 = ['_id' => 'custom-id', 'x' => 2];
    $doc3 = ['_id' => new MongoDB\BSON\ObjectId('0123456789abcdef01234567'), 'x' => 3];

    $id1 = $bulk->insert($doc1);
    $id2 = $bulk->insert($doc2);
    $id3 = $bulk->insert($doc3);

    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) "67f58058d1a0aa2fd80d55d0"
    }
    string(9) "custom-id"
    object(MongoDB\BSON\ObjectId)#4 (1) {
      ["oid"]=>
      string(24) "0123456789abcdef01234567"
    }

### 参考

- MongoDB\Driver\Manager::executeBulkWrite() - Execute one or more write operations
- MongoDB\Driver\WriteResult
- MongoDB\BSON\ObjectId
- MongoDB\BSON\Persistable

# MongoDB\Driver\BulkWrite::update

(mongodb >=1.0.0)

MongoDB\Driver\BulkWrite::update — Add an update operation to the bulk

### 説明

public function 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`
  sort | array|object | Specify which document the operation updates if the query matches multiple documents. The first document matched by the sort order will be updated. This option cannot be used if `"multi"` is `true`. This option is available in MongoDB 8.0+ and will result in an exception at execution time if specified for an older server version.
  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.21.0 | Added the `"sort"` option.
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

## 目次

- 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

# The MongoDB\Driver\BulkWriteCommand class

(mongodb >=2.1.0)

## はじめに

MongoDB\Driver\BulkWriteCommand collects one or more write operations that should be sent to the server using the » bulkWrite command introduced in MongoDB 8.0. After adding any number of insert, update, and delete operations, the command may be executed via MongoDB\Driver\Manager::executeBulkWriteCommand().

Unlike MongoDB\Driver\BulkWrite, where all write operations must target the same collection, each write operation within MongoDB\Driver\BulkWriteCommand may target a different collection.

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\BulkWriteCommand implements Countable {
/* メソッド */
public function __construct(?array `$options` = `null`)
public function count(): int
public function deleteMany(string `$namespace`, array|object `$filter`, ?array `$options` = `null`): void
public function deleteOne(string `$namespace`, array|object `$filter`, ?array `$options` = `null`): void
public function insertOne(string `$namespace`, array|object `$document`): mixed
public function replaceOne(
string `$namespace`,
array|object `$filter`,
array|object `$replacement`,
?array `$options` = `null`
): void
public function updateMany(
string `$namespace`,
array|object `$filter`,
array|object `$update`,
?array `$options` = `null`
): void
public function updateOne(
string `$namespace`,
array|object `$filter`,
array|object `$update`,
?array `$options` = `null`
): void
}

## 例

例1 Mixed write operations

Mixed write operations (i.e. inserts, updates, and deletes) will be sent to the server using a single » bulkWrite command.

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    // Delete documents from both collections
    $bulk->deleteMany('db.coll_one', []);
    $bulk->deleteMany('db.coll_two', []);

    // Insert documents into two collections
    $bulk->insertOne('db.coll_one', ['_id' => 1]);
    $bulk->insertOne('db.coll_two', ['_id' => 2]);
    $bulk->insertOne('db.coll_two', ['_id' => 3]);

    // Update a document in "coll_one"
    $bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    printf("Inserted %d document(s)\n", $result->getInsertedCount());
    printf("Updated  %d document(s)\n", $result->getModifiedCount());

    ?>

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

    Inserted 3 document(s)
    Updated  1 document(s)

例2 Ordered write operations causing an error

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 2]);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 3]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        $result = $e->getPartialResult();

        var_dump($e->getWriteErrors());
    }

    printf("Inserted %d document(s)\n", $result->getInsertedCount());

    ?>

上の例の出力は、 たとえば以下のようになります。

    array(1) {
      [3]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(3)
        ["info"]=>
        object(stdClass)#6 (0) {
        }
      }
    }
    Inserted 2 document(s)

## 参考

- MongoDB\Driver\Manager::executeBulkWriteCommand()
- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\Driver\Exception\BulkWriteCommandException
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\WriteConcernError
- MongoDB\Driver\WriteError

# MongoDB\Driver\BulkWriteCommand::__construct

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::__construct — Create a new BulkWriteCommand

### 説明

public function MongoDB\Driver\BulkWriteCommand::__construct(?array `$options` = `null`)

Constructs a new MongoDB\Driver\BulkWriteCommand, which may be used to perform many insert, update, and delete operations on multiple collections in a single request using the » bulkWrite command introduced in MongoDB 8.0. This differs from MongoDB\Driver\BulkWrite, which is supported by all server versions but limited to a single collection.

After all write operations have been added, this object may be executed with MongoDB\Driver\Manager::executeBulkWriteCommand().

### パラメータ

`options` (array)

  options
  Option | Type | Description | Default
  --- | --- | --- | ---
  bypassDocumentValidation | bool | If `true`, allows insert and update operations to circumvent document level validation. | `false`
  comment | mixed | An arbitrary comment to help trace the operation through the database profiler, currentOp output, and logs.
  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 | Whether the operations in this bulk write should be executed in the order in which they were specified. If `false`, writes will continue to be executed if an individual write fails. If `true`, writes will stop executing if an individual write fails. | `true`
  verboseResults | bool | Whether detailed results for each successful operation should be included in the returned MongoDB\Driver\BulkWriteCommandResult. | `false`

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 例

例1 MongoDB\Driver\BulkWriteCommand::__construct() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    // Delete documents from both collections
    $bulk->deleteMany('db.coll_one', []);
    $bulk->deleteMany('db.coll_two', []);

    // Insert documents into two collections
    $bulk->insertOne('db.coll_one', ['_id' => 1]);
    $bulk->insertOne('db.coll_two', ['_id' => 2]);
    $bulk->insertOne('db.coll_two', ['_id' => 3]);

    // Update a document in "coll_one"
    $bulk->updateOne('db.coll_one', ['_id' => 1], ['$set' => ['x' => 1]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    printf("Inserted %d document(s)\n", $result->getInsertedCount());
    printf("Updated  %d document(s)\n", $result->getModifiedCount());

    ?>

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

    Inserted 3 document(s)
    Updated  1 document(s)

### 参考

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::count

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::count — Count number of write operations in the BulkWriteCommand

### 説明

public function MongoDB\Driver\BulkWriteCommand::count(): int

Returns the number of write operations added to the MongoDB\Driver\BulkWriteCommand object.

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns number of write operations added to the MongoDB\Driver\BulkWriteCommand object.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 例

例1 MongoDB\Driver\BulkWriteCommand::count() example

    <?php

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['_id' => 1, 'x' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 2, 'x' => 2]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['x' => 1]]);
    $bulk->deleteMany('db.coll', ['x' => 1]);

    var_dump(count($bulk));

    ?>

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

    int(4)

# MongoDB\Driver\BulkWriteCommand::deleteMany

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::deleteMany — Add a deleteMany operation

### 説明

public function MongoDB\Driver\BulkWriteCommand::deleteMany(string `$namespace`, array|object `$filter`, ?array `$options` = `null`): void

Add a deleteMany operation to the MongoDB\Driver\BulkWriteCommand. All documents matching `filter` in the collection identified by `namespace` will be deleted.

### パラメータ

`namespace` (string)
  A fully qualified namespace (e.g. `"databaseName.collectionName"`).
`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`

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

### 戻り値

値を返しません。

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 例

例1 MongoDB\Driver\BulkWriteCommand::deleteMany() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->deleteMany('db.coll', ['x' => ['$gt' => 1]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### 参考

- MongoDB\Driver\BulkWriteCommand::deleteOne() - Add a deleteOne operation
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::deleteOne

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::deleteOne — Add a deleteOne operation

### 説明

public function MongoDB\Driver\BulkWriteCommand::deleteOne(string `$namespace`, array|object `$filter`, ?array `$options` = `null`): void

Add a deleteOne operation to the MongoDB\Driver\BulkWriteCommand. The first document matching `filter` in the collection identified by `namespace` will be deleted.

### パラメータ

`namespace` (string)
  A fully qualified namespace (e.g. `"databaseName.collectionName"`).
`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`

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

### 戻り値

値を返しません。

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 例

例1 MongoDB\Driver\BulkWriteCommand::deleteOne() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->deleteOne('db.coll', ['x' => 1]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### 参考

- MongoDB\Driver\BulkWriteCommand::deleteMany() - Add a deleteMany operation
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::insertOne

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::insertOne — Add an insertOne operation

### 説明

public function MongoDB\Driver\BulkWriteCommand::insertOne(string `$namespace`, array|object `$document`): mixed

Add an insertOne operation to the MongoDB\Driver\BulkWriteCommand. The document will be inserted into the collection identified by `namespace`.

### パラメータ

`namespace` (string)
  A fully qualified namespace (e.g. `"databaseName.collectionName"`).
`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.

### 例

例1 MongoDB\Driver\BulkWriteCommand::insertOne() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;

    $doc1 = ['x' => 1];
    $doc2 = ['_id' => 'custom-id', 'x' => 2];
    $doc3 = ['_id' => new MongoDB\BSON\ObjectId('0123456789abcdef01234567'), 'x' => 3];

    $id1 = $bulk->insertOne('db.coll', $doc1);
    $id2 = $bulk->insertOne('db.coll', $doc2);
    $id3 = $bulk->insertOne('db.coll', $doc3);

    var_dump($id1, $id2, $id3);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

上の例の出力は、 たとえば以下のようになります。

    object(MongoDB\BSON\ObjectId)#3 (1) {
      ["oid"]=>
      string(24) "67f58058d1a0aa2fd80d55d0"
    }
    string(9) "custom-id"
    object(MongoDB\BSON\ObjectId)#4 (1) {
      ["oid"]=>
      string(24) "0123456789abcdef01234567"
    }

### 参考

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command
- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\BSON\ObjectId

# MongoDB\Driver\BulkWriteCommand::replaceOne

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::replaceOne — Add a replaceOne operation

### 説明

public function MongoDB\Driver\BulkWriteCommand::replaceOne(
string `$namespace`,
array|object `$filter`,
array|object `$replacement`,
?array `$options` = `null`
): void

Add a replaceOne operation to the MongoDB\Driver\BulkWriteCommand. The first document matching `filter` in the collection identified by `namespace` will be replaced.

### パラメータ

`namespace` (string)
  A fully qualified namespace (e.g. `"databaseName.collectionName"`).
`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).

`replacement` (array|object)
  A replacement document.
`options`

  options
  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.
  sort | array|object | Specify which document the operation replaces if the query matches multiple documents. The first document matched by the sort order will be replaced.
  upsert | bool | If `filter` does not match an existing document, insert a single document. The document will be created from `replacement`. | `false`

### 戻り値

値を返しません。

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 例

例1 MongoDB\Driver\BulkWriteCommand::replaceOne() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->replaceOne('db.coll', ['x' => 1], ['x' => 1, 'y' => 2]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### 参考

- MongoDB\Driver\BulkWriteCommand::updateOne() - Add an updateOne operation
- MongoDB\Driver\BulkWriteCommand::updateMany() - Add an updateMany operation
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::updateMany

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::updateMany — Add an updateMany operation

### 説明

public function MongoDB\Driver\BulkWriteCommand::updateMany(
string `$namespace`,
array|object `$filter`,
array|object `$update`,
?array `$options` = `null`
): void

Add an updateMany operation to the MongoDB\Driver\BulkWriteCommand. All documents matching `filter` in the collection identified by `namespace` will be updated.

### パラメータ

`namespace` (string)
  A fully qualified namespace (e.g. `"databaseName.collectionName"`).
`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).

`update` (array|object)
  A document containing either update operators (e.g. `$set`) or an » aggregation pipeline.
`options`

  options
  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.
  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.
  upsert | bool | If `filter` does not match an existing document, insert a single document. The document will be created by applying operators in `update` to any field values in `filter`. | `false`

### 戻り値

値を返しません。

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 例

例1 MongoDB\Driver\BulkWriteCommand::updateMany() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->updateMany('db.coll', ['x' => ['$gt' => 1]], ['$set' => ['y' => 2]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### 参考

- MongoDB\Driver\BulkWriteCommand::replaceOne() - Add a replaceOne operation
- MongoDB\Driver\BulkWriteCommand::updateMany()
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command
- MongoDB\Driver\BulkWriteCommandResult

# MongoDB\Driver\BulkWriteCommand::updateOne

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommand::updateOne — Add an updateOne operation

### 説明

public function MongoDB\Driver\BulkWriteCommand::updateOne(
string `$namespace`,
array|object `$filter`,
array|object `$update`,
?array `$options` = `null`
): void

Add an updateOne operation to the MongoDB\Driver\BulkWriteCommand. The first document matching `filter` in the collection identified by `namespace` will be updated.

### パラメータ

`namespace` (string)
  A fully qualified namespace (e.g. `"databaseName.collectionName"`).
`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).

`update` (array|object)
  A document containing either update operators (e.g. `$set`) or an » aggregation pipeline.
`options`

  options
  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.
  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.
  sort | array|object | Specify which document the operation updates if the query matches multiple documents. The first document matched by the sort order will be updated.
  upsert | bool | If `filter` does not match an existing document, insert a single document. The document will be created by applying operators in `update` to any field values in `filter`. | `false`

### 戻り値

値を返しません。

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 例

例1 MongoDB\Driver\BulkWriteCommand::updateOne() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 2]]);

    $result = $manager->executeBulkWriteCommand($bulk);

    ?>

### 参考

- MongoDB\Driver\BulkWriteCommand::replaceOne() - Add a replaceOne operation
- MongoDB\Driver\BulkWriteCommand::updateMany() - Add an updateMany operation
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command
- MongoDB\Driver\BulkWriteCommandResult

## 目次

- MongoDB\Driver\BulkWriteCommand::__construct — Create a new BulkWriteCommand
- MongoDB\Driver\BulkWriteCommand::count — Count number of write operations in the BulkWriteCommand
- MongoDB\Driver\BulkWriteCommand::deleteMany — Add a deleteMany operation
- MongoDB\Driver\BulkWriteCommand::deleteOne — Add a deleteOne operation
- MongoDB\Driver\BulkWriteCommand::insertOne — Add an insertOne operation
- MongoDB\Driver\BulkWriteCommand::replaceOne — Add a replaceOne operation
- MongoDB\Driver\BulkWriteCommand::updateMany — Add an updateMany operation
- MongoDB\Driver\BulkWriteCommand::updateOne — Add an updateOne operation

# 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 with 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 function abortTransaction(): void
final public function advanceClusterTime(array|object `$clusterTime`): void
final public function advanceOperationTime(MongoDB\BSON\TimestampInterface `$operationTime`): void
final public function commitTransaction(): void
final private function __construct()
final public function endSession(): void
final public function getClusterTime(): ?object
final public function getLogicalSessionId(): object
final public function getOperationTime(): ?MongoDB\BSON\Timestamp
final public function getServer(): ?MongoDB\Driver\Server
final public function getTransactionOptions(): ?array
final public function getTransactionState(): string
final public function isDirty(): bool
final public function isInTransaction(): bool
final public function 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

(mongodb >=1.5.0)

MongoDB\Driver\Session::abortTransaction — Aborts a transaction

### 説明

final public function 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

# MongoDB\Driver\Session::advanceClusterTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::advanceClusterTime — Advances the cluster time for this session

### 説明

final public function 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

# MongoDB\Driver\Session::advanceOperationTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::advanceOperationTime — Advances the operation time for this session

### 説明

final public function 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

# MongoDB\Driver\Session::commitTransaction

(mongodb >=1.5.0)

MongoDB\Driver\Session::commitTransaction — Commits a transaction

### 説明

final public function 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 `"UnknownTransactionCommitResult"` 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

# MongoDB\Driver\Session::__construct

(mongodb >=1.4.0)

MongoDB\Driver\Session::__construct — Create a new Session (not used)

### 説明

final private function 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

# MongoDB\Driver\Session::endSession

(mongodb >=1.5.0)

MongoDB\Driver\Session::endSession — Terminates a session

### 説明

final public function 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

# MongoDB\Driver\Session::getClusterTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::getClusterTime — Returns the cluster time for this session

### 説明

final public function 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

# MongoDB\Driver\Session::getLogicalSessionId

(mongodb >=1.4.0)

MongoDB\Driver\Session::getLogicalSessionId — Returns the logical session ID for this session

### 説明

final public function 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.

# MongoDB\Driver\Session::getOperationTime

(mongodb >=1.4.0)

MongoDB\Driver\Session::getOperationTime — Returns the operation time for this session

### 説明

final public function 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

# MongoDB\Driver\Session::getServer

(mongodb >=1.6.0)

MongoDB\Driver\Session::getServer — Returns the server to which this session is pinned

### 説明

final public function 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.

# MongoDB\Driver\Session::getTransactionOptions

(mongodb >=1.7.0)

MongoDB\Driver\Session::getTransactionOptions — Returns options for the currently running transaction

### 説明

final public function 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

# MongoDB\Driver\Session::getTransactionState

(mongodb >=1.7.0)

MongoDB\Driver\Session::getTransactionState — Returns the current transaction state for this session

### 説明

final public function 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

# MongoDB\Driver\Session::isDirty

(mongodb >=1.13.0)

MongoDB\Driver\Session::isDirty — Returns whether the session has been marked as dirty

### 説明

final public function 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.

# MongoDB\Driver\Session::isInTransaction

(mongodb >=1.6.0)

MongoDB\Driver\Session::isInTransaction — Returns whether a multi-document transaction is in progress

### 説明

final public function 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

# MongoDB\Driver\Session::startTransaction

(mongodb >=1.5.0)

MongoDB\Driver\Session::startTransaction — Starts a transaction

### 説明

final public function 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

## 目次

- 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

# 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 QUERY_TYPE_EQUALITY = equality;
const string QUERY_TYPE_RANGE = range;
/* メソッド */
final public function addKeyAltName(MongoDB\BSON\Binary `$keyId`, string `$keyAltName`): ?object
final public function __construct(array `$options`)
final public function createDataKey(string `$kmsProvider`, ?array `$options` = `null`): MongoDB\BSON\Binary
final public function decrypt(MongoDB\BSON\Binary `$value`): mixed
final public function deleteKey(MongoDB\BSON\Binary `$keyId`): object
final public function encrypt(mixed `$value`, ?array `$options` = `null`): MongoDB\BSON\Binary
final public function encryptExpression(array|object `$expr`, ?array `$options` = `null`): object
final public function getKey(MongoDB\BSON\Binary `$keyId`): ?object
final public function getKeyByAltName(string `$keyAltName`): ?object
final public function getKeys(): MongoDB\Driver\Cursor
final public function removeKeyAltName(MongoDB\BSON\Binary `$keyId`, string `$keyAltName`): ?object
final public function 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 extension does not yet support range queries for Decimal128 BSON field types.

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

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | Removed `MongoDB\Driver\ClientEncryption::ALGORITHM_RANGE_PREVIEW` and `MongoDB\Driver\ClientEncryption::QUERY_TYPE_RANGE_PREVIEW`.
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

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::addKeyAltName — Adds an alternate name to a key document

### 説明

final public function 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

# MongoDB\Driver\ClientEncryption::__construct

(mongodb >=1.14.0)

MongoDB\Driver\ClientEncryption::__construct — Create a new ClientEncryption object

### 説明

final public function 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. This option is required.
  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

# MongoDB\Driver\ClientEncryption::createDataKey

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::createDataKey — Creates a key document

### 説明

final public function 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.
  delegated | bool | Optional. If true, this key should be decrypted by the KMIP server.
  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.20.0 | Added `"delegated"` to the KMIP provider masterKey options.
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.

# MongoDB\Driver\ClientEncryption::decrypt

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::decrypt — Decrypt a value

### 説明

final public function 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

# MongoDB\Driver\ClientEncryption::deleteKey

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::deleteKey — Deletes a key document

### 説明

final public function 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.

# MongoDB\Driver\ClientEncryption::encrypt

(mongodb >=1.7.0)

MongoDB\Driver\ClientEncryption::encrypt — Encrypt a value

### 説明

final public function 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` 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 | Optional. 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 | Optional. 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.20.0 | Added the `"trimFactor"` range option. The `"sparsity"` range option is now optional.
PECL mongodb 1.16.0 | Added the `"rangeOpts"` option.
PECL mongodb 1.14.0 | Added the `"contentionFactor"` and `"queryType"` options.

### 参考

- MongoDB\Driver\ClientEncryption::decrypt() - Decrypt a value
- MongoDB\Driver\ClientEncryption::encryptExpression() - 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 function 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 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` 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 | Optional. 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 | Optional. 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

### 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 1.20.0 | Added the `"trimFactor"` range option. The `"sparsity"` range option is now optional.

### 参考

- MongoDB\Driver\Manager::__construct() - Create new MongoDB Manager
- MongoDB\Driver\ClientEncryption::encrypt() - Encrypt a value

# MongoDB\Driver\ClientEncryption::getKey

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::getKey — Gets a key document

### 説明

final public function 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.

# MongoDB\Driver\ClientEncryption::getKeyByAltName

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::getKeyByAltName — Gets a key document by an alternate name

### 説明

final public function 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

# MongoDB\Driver\ClientEncryption::getKeys

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::getKeys — Gets all key documents

### 説明

final public function 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.

# MongoDB\Driver\ClientEncryption::removeKeyAltName

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::removeKeyAltName — Removes an alternate name from a key document

### 説明

final public function 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

# MongoDB\Driver\ClientEncryption::rewrapManyDataKey

(mongodb >=1.15.0)

MongoDB\Driver\ClientEncryption::rewrapManyDataKey — Rewraps data keys

### 説明

final public function 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.
  delegated | bool | Optional. If true, this key should be decrypted by the KMIP server.

### 戻り値

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.

### 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 1.20.0 | Added `"delegated"` to the KMIP provider masterKey options.

## 目次

- 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

# 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 function bsonSerialize(): stdClass
final public function __construct(string `$version`, ?bool `$strict` = `null`, ?bool `$deprecationErrors` = `null`)
}

## 定義済み定数

`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

(mongodb >=1.10.0)

MongoDB\Driver\ServerApi::bsonSerialize — Returns an object for BSON serialization

### 説明

final public function 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

# MongoDB\Driver\ServerApi::__construct

(mongodb >=1.10.0)

MongoDB\Driver\ServerApi::__construct — Create a new ServerApi instance

### 説明

final public function 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.

## 目次

- MongoDB\Driver\ServerApi::bsonSerialize — Returns an object for BSON serialization
- MongoDB\Driver\ServerApi::__construct — Create a new ServerApi instance

# 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";
/* プロパティ */
public readonly string|int|null $w;
public readonly ?bool $j;
public readonly int $wtimeout;
/* メソッド */
final public function bsonSerialize(): stdClass
final public function __construct(string|int `$w`, ?int `$wtimeout` = `null`, ?bool `$journal` = `null`)
final public function getJournal(): ?bool
final public function getW(): string|int|null
final public function getWtimeout(): int
final public function isDefault(): bool
}

## プロパティ

w
  The write concern value (integer number of nodes, the string `"majority"`, or a custom write concern tag name), or `null` if not set.
j
  Whether write operations must be committed to the journal before acknowledged, or `null` if not specified.
wtimeout
  The timeout in milliseconds to wait for write concern acknowledgement. A value of `0` means to wait indefinitely.

## 定義済み定数

`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 2.3.0 | Added public readonly properties.
PECL mongodb 1.7.0 | Implements Serializable.
PECL mongodb 1.2.0 | Implements MongoDB\BSON\Serializable.

# MongoDB\Driver\WriteConcern::bsonSerialize

(mongodb >=1.2.0)

MongoDB\Driver\WriteConcern::bsonSerialize — Returns an object for BSON serialization

### 説明

final public function 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\Document::fromPHP($wc)->toRelaxedExtendedJSON();

    ?>

上の例の出力は、 たとえば以下のようになります。

    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\Document::fromPHP($wc)->toRelaxedExtendedJSON();

    ?>

上の例の出力は、 たとえば以下のようになります。

    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

# MongoDB\Driver\WriteConcern::__construct

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::__construct — Create a new WriteConcern

### 説明

final public function 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

# MongoDB\Driver\WriteConcern::getJournal

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getJournal — Returns the WriteConcern's "journal" option

### 説明

final public function 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

# MongoDB\Driver\WriteConcern::getW

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getW — Returns the WriteConcern's "w" option

### 説明

final public function 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

# MongoDB\Driver\WriteConcern::getWtimeout

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcern::getWtimeout — Returns the WriteConcern's "wtimeout" option

### 説明

final public function 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

# MongoDB\Driver\WriteConcern::isDefault

(mongodb >=1.3.0)

MongoDB\Driver\WriteConcern::isDefault — Checks if this is the default write concern

### 説明

final public function 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

## 目次

- 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

# The MongoDB\Driver\ReadPreference class

(mongodb >=1.0.0)

## はじめに

## クラス概要

final class MongoDB\Driver\ReadPreference implements MongoDB\BSON\Serializable, Serializable {
/* プロパティ */
public readonly string $mode;
public readonly ?array $tags;
public readonly int $maxStalenessSeconds;
public readonly ?object $hedge;
/* 定数 */
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 function bsonSerialize(): stdClass
final public function __construct(string `$mode`, ?array `$tagSets` = `null`, ?array `$options` = `null`)
final public function getHedge(): ?object
final public function getMaxStalenessSeconds(): int
final public function getMode(): int
final public function getModeString(): string
final public function getTagSets(): array
}

## プロパティ

mode
  The read preference mode as a string (e.g. `"primary"`, `"secondary"`).
tags
  The tag set list used by the read preference, or `null` if no tag sets were specified.
maxStalenessSeconds
  The maximum staleness in seconds for reads, or `MongoDB\Driver\ReadPreference::NO_MAX_STALENESS` if no maximum staleness was specified.
hedge
  A document specifying the hedge options for the read preference, or `null` if no hedge options were specified.
  警告

  This property is deprecated as hedged reads are deprecated in MongoDB 8.0.

## 定義済み定数

`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 2.3.0 | Added public readonly properties.
PECL mongodb 2.0.0 | Removed the `MongoDB\Driver\ReadPreference::RP_PRIMARY`, `MongoDB\Driver\ReadPreference::RP_PRIMARY_PREFERRED`, `MongoDB\Driver\ReadPreference::RP_SECONDARY`, `MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED`, and `MongoDB\Driver\ReadPreference::RP_NEAREST` constants. The getMode() method was also removed.
PECL mongodb 1.20.0 | Deprecated the `MongoDB\Driver\ReadPreference::RP_PRIMARY`, `MongoDB\Driver\ReadPreference::RP_PRIMARY_PREFERRED`, `MongoDB\Driver\ReadPreference::RP_SECONDARY`, `MongoDB\Driver\ReadPreference::RP_SECONDARY_PREFERRED`, and `MongoDB\Driver\ReadPreference::RP_NEAREST` constants.
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`, and `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

(mongodb >=1.2.0)

MongoDB\Driver\ReadPreference::bsonSerialize — Returns an object for BSON serialization

### 説明

final public function 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::PRIMARY);
    var_dump($rp->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rp)->toRelaxedExtendedJSON();

    ?>

上の例の出力は、 たとえば以下のようになります。

    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::SECONDARY,
        [
            ['dc' => 'ny'],
            ['dc' => 'sf', 'use' => 'reporting'],
            []
        ]
    );
    var_dump($rp->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rp)->toRelaxedExtendedJSON();

    ?>

上の例の出力は、 たとえば以下のようになります。

    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::SECONDARY,
        null,
        ['maxStalenessSeconds' => 120]
    );
    var_dump($rp->bsonSerialize());

    echo "\n", MongoDB\BSON\Document::fromPHP($rp)->toRelaxedExtendedJSON();

    ?>

上の例の出力は、 たとえば以下のようになります。

    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

# MongoDB\Driver\ReadPreference::__construct

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::__construct — Create a new ReadPreference

### 説明

final public function MongoDB\Driver\ReadPreference::__construct(string `$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
  --- | ---
  `"primary"` | All operations read from the current replica set primary. This is the default read preference for MongoDB.
  `"primaryPreferred"` | In most situations, operations read from the primary but if it is unavailable, operations read from secondary members.
  `"secondary"` | All operations read from the secondary members of the replica set.
  `"secondaryPreferred"` | In most situations, operations read from secondary members but if no secondary members are available, operations read from the primary.
  `"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 `"primary"` mode and, in general, only apply when selecting a secondary member of a set for a read operation. However, the `"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 `"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 2.0.0 | Passing an int for the `mode` argument is no longer supported.
PECL mongodb 1.20.0 | Passing an int for the `mode` argument is DEPRECATED.
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::SECONDARY_PREFERRED));

    /* Prefer a node in the New York data center with lowest latency. */
    var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::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::SECONDARY, null, ['maxStalenessSeconds' => 120]));

    /* Explicitly enable server hedged reads */
    var_dump(new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::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

# MongoDB\Driver\ReadPreference::getHedge

(mongodb >=1.8.0)

MongoDB\Driver\ReadPreference::getHedge — Returns the ReadPreference's "hedge" option

### 説明

final public function MongoDB\Driver\ReadPreference::getHedge(): ?object

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the ReadPreference's "hedge" option.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参考

- » Read Preference reference

# MongoDB\Driver\ReadPreference::getMaxStalenessSeconds

(mongodb >=1.2.0)

MongoDB\Driver\ReadPreference::getMaxStalenessSeconds — Returns the ReadPreference's "maxStalenessSeconds" option

### 説明

final public function 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::SECONDARY);
    var_dump($rp->getMaxStalenessSeconds());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, [
        'maxStalenessSeconds' => MongoDB\Driver\ReadPreference::NO_MAX_STALENESS,
    ]);
    var_dump($rp->getMaxStalenessSeconds());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, [
        'maxStalenessSeconds' => MongoDB\Driver\ReadPreference::SMALLEST_MAX_STALENESS_SECONDS,
    ]);
    var_dump($rp->getMaxStalenessSeconds());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY, null, [
        'maxStalenessSeconds' => 1000,
    ]);
    var_dump($rp->getMaxStalenessSeconds());

    ?>

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

    int(-1)
    int(-1)
    int(90)
    int(1000)

### 参考

- » Read Preference reference

# MongoDB\Driver\ReadPreference::getMode

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::getMode — Returns the ReadPreference's "mode" option

警告

This function has been DEPRECATED as of extension version 1.20.0 and was removed in 2.0. Applications should use MongoDB\Driver\ReadPreference::getModeString() instead.

### 説明

final public function MongoDB\Driver\ReadPreference::getMode(): int

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the ReadPreference's "mode" option.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This method was removed.

### 例

例1 MongoDB\Driver\ReadPreference::getMode() example

    <?php

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY);
    var_dump($rp->getMode());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY_PREFERRED);
    var_dump($rp->getMode());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY);
    var_dump($rp->getMode());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::SECONDARY_PREFERRED);
    var_dump($rp->getMode());

    $rp = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::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
- » Read Preference reference

# MongoDB\Driver\ReadPreference::getModeString

(mongodb >=1.7.0)

MongoDB\Driver\ReadPreference::getModeString — Returns the ReadPreference's "mode" option

### 説明

final public function 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

# MongoDB\Driver\ReadPreference::getTagSets

(mongodb >=1.0.0)

MongoDB\Driver\ReadPreference::getTagSets — Returns the ReadPreference's "tagSets" option

### 説明

final public function 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::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

## 目次

- 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
- MongoDB\Driver\ReadPreference::getTagSets — Returns the ReadPreference's "tagSets" option

# 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 {
/* プロパティ */
public readonly ?string $level;
/* 定数 */
const string AVAILABLE = "available";
const string LINEARIZABLE = "linearizable";
const string LOCAL = "local";
const string MAJORITY = "majority";
const string SNAPSHOT = "snapshot";
/* メソッド */
final public function bsonSerialize(): stdClass
final public function __construct(?string `$level` = `null`)
final public function getLevel(): ?string
final public function isDefault(): bool
}

## プロパティ

level
  The read concern level. `null` if no level was specified.

## 定義済み定数

`MongoDB\Driver\ReadConcern::AVAILABLE`
  Default for reads against secondaries when `afterClusterTime`and `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 2.3.0 | Added public readonly properties.
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

(mongodb >=1.2.0)

MongoDB\Driver\ReadConcern::bsonSerialize — Returns an object for BSON serialization

### 説明

final public function 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\Document::fromPHP($rc)->toRelaxedExtendedJSON();

    ?>

上の例の出力は、 たとえば以下のようになります。

    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\Document::fromPHP($rc)->toRelaxedExtendedJSON();

    ?>

上の例の出力は、 たとえば以下のようになります。

    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

# MongoDB\Driver\ReadConcern::__construct

(mongodb >=1.0.0)

MongoDB\Driver\ReadConcern::__construct — Create a new ReadConcern

### 説明

final public function 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

# MongoDB\Driver\ReadConcern::getLevel

(mongodb >=1.0.0)

MongoDB\Driver\ReadConcern::getLevel — Returns the ReadConcern's "level" option

### 説明

final public function 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

# MongoDB\Driver\ReadConcern::isDefault

(mongodb >=1.3.0)

MongoDB\Driver\ReadConcern::isDefault — Checks if this is the default read concern

### 説明

final public function 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 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

## 目次

- 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

# 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 {
/* メソッド */
final private function __construct()
public function current(): array|object|null
final public function getId(): MongoDB\BSON\Int64
final public function getServer(): MongoDB\Driver\Server
final public function isDead(): bool
public function key(): int
public function next(): void
public function rewind(): void
final public function setTypeMap(array `$typemap`): void
final public function toArray(): array
public function 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

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::__construct — Create a new Cursor (not used)

### 説明

final private function 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

# MongoDB\Driver\Cursor::current

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::current — Returns the current element

### 説明

public function 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() - 現在の要素を返す

# MongoDB\Driver\Cursor::getId

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::getId — Returns the ID for this cursor

### 説明

final public function MongoDB\Driver\Cursor::getId(): MongoDB\BSON\Int64

Returns the ID for this cursor, which uniquely identifies the cursor on the server.

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the ID for this cursor. The ID will be returned as a MongoDB\BSON\Int64 object.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | The return type was changed to MongoDB\BSON\Int64. The `asInt64` parameter was removed.
PECL mongodb 1.20.0 | Deprecated returning a MongoDB\Driver\CursorId. Added the `asInt64` argument to ease migration for future versions. If `asInt64` is `true`, the ID will be returned as a MongoDB\BSON\Int64.

### 例

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

    ?>

上の例の出力は、 たとえば以下のようになります。

    object(MongoDB\BSON\Int64)#5 (1) {
      ["integer"]=>
      string(11) "94810124093"
    }

### 参考

- MongoDB\BSON\Int64

# MongoDB\Driver\Cursor::getServer

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::getServer — Returns the server associated with this cursor

### 説明

final public function 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

# 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 function 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

# MongoDB\Driver\Cursor::key

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::key — Returns the current result's index within the cursor

### 説明

public function MongoDB\Driver\Cursor::key(): int

### パラメータ

この関数にはパラメータはありません。

### 戻り値

The current result's numeric index within the cursor.

### 参考

- Iterator::key() - 現在の要素のキーを返す

# MongoDB\Driver\Cursor::next

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::next — Advances the cursor to the next result

### 説明

public function 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() - 次の要素に進む

# MongoDB\Driver\Cursor::rewind

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::rewind — Rewind the cursor to the first result

### 説明

public function 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() - イテレータの最初の要素に巻き戻す

# MongoDB\Driver\Cursor::setTypeMap

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::setTypeMap — Sets a type map to use for BSON unserialization

### 説明

final public function 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

# MongoDB\Driver\Cursor::toArray

(mongodb >=1.0.0)

MongoDB\Driver\Cursor::toArray — Returns an array containing all results for this cursor

### 説明

final public function 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

# MongoDB\Driver\Cursor::valid

(mongodb >=1.9.0)

MongoDB\Driver\Cursor::valid — Checks if the current position in the cursor is valid

### 説明

public function MongoDB\Driver\Cursor::valid(): bool

### パラメータ

この関数にはパラメータはありません。

### 戻り値

`true` if the current cursor position is valid, `false` otherwise.

### 参考

- Iterator::valid() - 現在位置が有効かどうかを調べる

## 目次

- 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

# 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().

警告

This class has been DEPRECATED as of extension version 1.20.0 and was removed in 2.0. Applications have to update their usage of MongoDB\Driver\Cursor::getId() to return MongoDB\BSON\Int64 instead.

## クラス概要

final class MongoDB\Driver\CursorId implements Serializable, Stringable {
/* メソッド */
final private function __construct()
final public function __toString(): string
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This class was removed.
PECL mongodb 1.20.0 | This class has been deprecated and will be removed in version 2.0.
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.
PECL mongodb 1.7.0 | Implements Serializable.

# MongoDB\Driver\CursorId::__construct

(mongodb >=1.0.0)

MongoDB\Driver\CursorId::__construct — Create a new CursorId (not used)

### 説明

final private function 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

# MongoDB\Driver\CursorId::__toString

(mongodb >=1.0.0)

MongoDB\Driver\CursorId::__toString — String representation of the cursor ID

### 説明

final public function 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

## 目次

- MongoDB\Driver\CursorId::__construct — Create a new CursorId (not used)
- MongoDB\Driver\CursorId::__toString — String representation of the cursor ID

# 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 Iterator {
/* メソッド */
abstract public function getId(): MongoDB\BSON\Int64
abstract public function getServer(): MongoDB\Driver\Server
abstract public function isDead(): bool
abstract public function setTypeMap(array `$typemap`): void
abstract public function toArray(): array
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This interface now extends Iterator. Return types previously declared as tentative are now enforced.
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

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::getId — Returns the ID for this cursor

### 説明

abstract public function MongoDB\Driver\CursorInterface::getId(): MongoDB\BSON\Int64

Returns the ID for this cursor, which uniquely identifies the cursor on the server.

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the ID for this cursor.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 1.20.0 | Added MongoDB\BSON\Int64 to the tentative return type for this method. MongoDB\Driver\CursorId will be removed from the return type in version 2.0.

### 参考

- MongoDB\Driver\Cursor::getId() - Returns the ID for this cursor
- MongoDB\Driver\CursorId
- MongoDB\BSON\Int64

# MongoDB\Driver\CursorInterface::getServer

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::getServer — Returns the server associated with this cursor

### 説明

abstract public function 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

# MongoDB\Driver\CursorInterface::isDead

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::isDead — Checks if the cursor may have additional results

### 説明

abstract public function 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

# MongoDB\Driver\CursorInterface::setTypeMap

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::setTypeMap — Sets a type map to use for BSON unserialization

### 説明

abstract public function 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

# MongoDB\Driver\CursorInterface::toArray

(mongodb >=1.6.0)

MongoDB\Driver\CursorInterface::toArray — Returns an array containing all results for this cursor

### 説明

abstract public function 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

## 目次

- 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

# 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 function __construct()
final public function executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$options` = `null`): MongoDB\Driver\WriteResult
final public function executeBulkWriteCommand(MongoDB\Driver\BulkWriteCommand `$bulk`, ?array `$options` = `null`): MongoDB\Driver\BulkWriteCommandResult
final public function executeCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeQuery(string `$namespace`, MongoDB\Driver\Query `$query`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeReadCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeReadWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function executeWriteCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$options` = `null`): MongoDB\Driver\Cursor
final public function getHost(): string
final public function getInfo(): array
final public function getLatency(): ?integer
final public function getPort(): int
final public function getServerDescription(): MongoDB\Driver\ServerDescription
final public function getTags(): array
final public function getType(): int
final public function isArbiter(): bool
final public function isHidden(): bool
final public function isPassive(): bool
final public function isPrimary(): bool
final public function 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 member 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

(mongodb >=1.0.0)

MongoDB\Driver\Server::__construct — Create a new Server (not used)

### 説明

final private function 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

# MongoDB\Driver\Server::executeBulkWrite

(mongodb >=1.0.0)

MongoDB\Driver\Server::executeBulkWrite — Execute one or more write operations on this server

### 説明

final public function MongoDB\Driver\Server::executeBulkWrite(string `$namespace`, MongoDB\Driver\BulkWrite `$bulk`, ?array `$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 2.0.0 | The `options` parameter no longer accepts a MongoDB\Driver\WriteConcern instance.
PECL mongodb 1.21.0 | Passing a MongoDB\Driver\WriteConcern object as `options` is deprecated and will be removed in 2.0.
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

# MongoDB\Driver\Server::executeBulkWriteCommand

(mongodb >=2.1.0)

MongoDB\Driver\Server::executeBulkWriteCommand — Execute write operations on this server using the bulkWrite command

### 説明

final public function MongoDB\Driver\Server::executeBulkWriteCommand(MongoDB\Driver\BulkWriteCommand `$bulk`, ?array `$options` = `null`): MongoDB\Driver\BulkWriteCommandResult

Executes one or more write operations on this server using the » bulkWrite command introduced in MongoDB 8.0.

A MongoDB\Driver\BulkWriteCommand can be constructed with one or more write operations of varying types (e.g. inserts, updates, and deletes). Each write operation may target a different collection.

The default value for the `"writeConcern"` option will be inferred from an active transaction (indicated by the `"session"` option), followed by the connection URI.

### パラメータ

`bulk` (MongoDB\Driver\BulkWriteCommand)
  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\BulkWriteCommandResult 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\BulkWriteCommand 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\BulkWriteCommandException on any write failure (e.g. command failure, write or write concern error)
- Throws MongoDB\Driver\Exception\RuntimeException on other errors.

### 参考

- MongoDB\Driver\BulkWriteCommand
- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command

# MongoDB\Driver\Server::executeCommand

(mongodb >=1.0.0)

MongoDB\Driver\Server::executeCommand — Execute a database command on this server

### 説明

final public function MongoDB\Driver\Server::executeCommand(string `$db`, MongoDB\Driver\Command `$command`, ?array `$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 2.0.0 | The `options` parameter no longer accepts a MongoDB\Driver\ReadPreference instance.
PECL mongodb 1.21.0 | Passing a MongoDB\Driver\ReadPreference object as `options` is deprecated and will be removed in 2.0.
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

# MongoDB\Driver\Server::executeQuery

(mongodb >=1.0.0)

MongoDB\Driver\Server::executeQuery — Execute a database query on this server

### 説明

final public function MongoDB\Driver\Server::executeQuery(string `$namespace`, MongoDB\Driver\Query `$query`, ?array `$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 2.0.0 | The `options` parameter no longer accepts a MongoDB\Driver\ReadPreference instance.
PECL mongodb 1.21.0 | Passing a MongoDB\Driver\ReadPreference object as `options` is deprecated and will be removed in 2.0.
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

# MongoDB\Driver\Server::executeReadCommand

(mongodb >=1.4.0)

MongoDB\Driver\Server::executeReadCommand — Execute a database command that reads on this server

### 説明

final public function 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

# 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 function 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

# MongoDB\Driver\Server::executeWriteCommand

(mongodb >=1.4.0)

MongoDB\Driver\Server::executeWriteCommand — Execute a database command that writes on this server

### 説明

final public function 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

# MongoDB\Driver\Server::getHost

(mongodb >=1.0.0)

MongoDB\Driver\Server::getHost — Returns the hostname of this server

### 説明

final public function 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/");
    $server = $manager->selectServer();

    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

# MongoDB\Driver\Server::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\Server::getInfo — Returns an array of information describing this server

### 説明

final public function 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

# MongoDB\Driver\Server::getLatency

(mongodb >=1.0.0)

MongoDB\Driver\Server::getLatency — Returns the latency of this server in milliseconds

### 説明

final public function 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/");
    $server = $manager->selectServer();

    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

# MongoDB\Driver\Server::getPort

(mongodb >=1.0.0)

MongoDB\Driver\Server::getPort — Returns the port on which this server is listening

### 説明

final public function 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/");
    $server = $manager->selectServer();

    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

# MongoDB\Driver\Server::getServerDescription

(mongodb >=1.13.0)

MongoDB\Driver\Server::getServerDescription — Returns a ServerDescription for this server

### 説明

final public function 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.

# 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 function 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

# MongoDB\Driver\Server::getType

(mongodb >=1.0.0)

MongoDB\Driver\Server::getType — Returns an integer denoting the type of this server

### 説明

final public function 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

# 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 function 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

# 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 function 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

# 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 function 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

# 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 function 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

# 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 function 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

## 目次

- 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::executeBulkWriteCommand — Execute write operations on this server using the bulkWrite command
- 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

# 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 function getHelloResponse(): array
final public function getHost(): string
final public function getLastUpdateTime(): int
final public function getPort(): int
final public function getRoundTripTime(): ?int
final public function 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

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getHelloResponse — Returns the server's most recent "hello" response

### 説明

final public function 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

# MongoDB\Driver\ServerDescription::getHost

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getHost — Returns the hostname of this server

### 説明

final public function 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

# MongoDB\Driver\ServerDescription::getLastUpdateTime

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getLastUpdateTime — Returns the server's last update time in microseconds

### 説明

final public function 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.

# MongoDB\Driver\ServerDescription::getPort

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getPort — Returns the port on which this server is listening

### 説明

final public function 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

# MongoDB\Driver\ServerDescription::getRoundTripTime

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getRoundTripTime — Returns the server's round trip time in milliseconds

### 説明

final public function 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

# MongoDB\Driver\ServerDescription::getType

(mongodb >=1.13.0)

MongoDB\Driver\ServerDescription::getType — Returns a string denoting the type of this server

### 説明

final public function 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

## 目次

- 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

# 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 function getServers(): array
final public function getType(): string
final public function hasReadableServer(?MongoDB\Driver\ReadPreference `$readPreference` = `null`): bool
final public function 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

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::getServers — Returns the servers in the topology

### 説明

final public function 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.

# MongoDB\Driver\TopologyDescription::getType

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::getType — Returns a string denoting the type of this topology

### 説明

final public function 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.

# MongoDB\Driver\TopologyDescription::hasReadableServer

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::hasReadableServer — Returns whether the topology has a readable server

### 説明

final public function 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.

# MongoDB\Driver\TopologyDescription::hasWritableServer

(mongodb >=1.13.0)

MongoDB\Driver\TopologyDescription::hasWritableServer — Returns whether the topology has a writable server

### 説明

final public function 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.

## 目次

- 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

# 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 {
/* プロパティ */
public readonly string $message;
public readonly int $code;
public readonly ?object $info;
/* メソッド */
final public function getCode(): int
final public function getInfo(): ?object
final public function getMessage(): string
}

## プロパティ

message
  The error message.
code
  The error code.
info
  Additional information for the error, or `null` if not available.

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.

# MongoDB\Driver\WriteConcernError::getCode

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getCode — Returns the WriteConcernError's error code

### 説明

final public function 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' => $writeConcern]);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteConcernError()->getCode());
    }

    ?>

上の例の出力は、 たとえば以下のようになります。

    int(64)

### 参考

- » Write Concern reference

# MongoDB\Driver\WriteConcernError::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getInfo — Returns metadata document for the WriteConcernError

### 説明

final public function 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' => $writeConcern]);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteConcernError()->getInfo());
    }

    ?>

上の例の出力は、 たとえば以下のようになります。

    object(stdClass)#1 (1) {
      ["wtimeout"]=>
      bool(true)
    }

### 参考

- » Write Concern reference

# MongoDB\Driver\WriteConcernError::getMessage

(mongodb >=1.0.0)

MongoDB\Driver\WriteConcernError::getMessage — Returns the WriteConcernError's error message

### 説明

final public function 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' => $writeConcern]);
    } catch(MongoDB\Driver\Exception\BulkWriteException $e) {
        var_dump($e->getWriteResult()->getWriteConcernError()->getMessage());
    }

    ?>

上の例の出力は、 たとえば以下のようになります。

    string(33) "waiting for replication timed out"

### 参考

- » Write Concern reference

## 目次

- 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

# 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 {
/* プロパティ */
public readonly string $message;
public readonly int $code;
public readonly int $index;
public readonly ?object $info;
/* メソッド */
final public function getCode(): int
final public function getIndex(): int
final public function getInfo(): ?object
final public function getMessage(): string
}

## プロパティ

message
  The error message.
code
  The error code.
index
  The index of the write operation within the MongoDB\Driver\BulkWrite that caused the error.
info
  Additional information for the error, or `null` if not available.

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.

# MongoDB\Driver\WriteError::getCode

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getCode — Returns the WriteError's error code

### 説明

final public function 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)

# 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 function 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

# MongoDB\Driver\WriteError::getInfo

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getInfo — Returns metadata document for the WriteError

### 説明

final public function 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.

# MongoDB\Driver\WriteError::getMessage

(mongodb >=1.0.0)

MongoDB\Driver\WriteError::getMessage — Returns the WriteError's error message

### 説明

final public function 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 }"

## 目次

- 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

# 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 {
/* プロパティ */
public readonly ?int $insertedCount;
public readonly ?int $matchedCount;
public readonly ?int $modifiedCount;
public readonly ?int $deletedCount;
public readonly ?int $upsertedCount;
public readonly MongoDB\Driver\Server $server;
public readonly array $upsertedIds;
public readonly array $writeErrors;
public readonly ?MongoDB\Driver\WriteConcernError $writeConcernError;
public readonly ?MongoDB\Driver\WriteConcern $writeConcern;
public readonly array $errorReplies;
/* メソッド */
final public function getDeletedCount(): int
final public function getInsertedCount(): int
final public function getMatchedCount(): int
final public function getModifiedCount(): int
final public function getServer(): MongoDB\Driver\Server
final public function getUpsertedCount(): int
final public function getUpsertedIds(): array
final public function getWriteConcernError(): ?MongoDB\Driver\WriteConcernError
final public function getWriteErrors(): array
final public function isAcknowledged(): bool
}

## プロパティ

insertedCount
  The number of documents inserted (excluding upserts), or `null` if the write concern did not request acknowledgement.
matchedCount
  The number of documents matched by update and replace operations, or `null` if the write concern did not request acknowledgement.
modifiedCount
  The number of documents modified by update and replace operations, or `null` if the write concern did not request acknowledgement or if the server did not report this information.
deletedCount
  The number of documents deleted, or `null` if the write concern did not request acknowledgement.
upsertedCount
  The number of documents upserted, or `null` if the write concern did not request acknowledgement.
server
  The server that executed the bulk write.
upsertedIds
  An array of `_id` values for upserted documents. Array keys will correspond to the index of the write operation from MongoDB\Driver\BulkWrite.
writeErrors
  An array of MongoDB\Driver\WriteErrors for any write errors that occurred during execution.
writeConcernError
  The MongoDB\Driver\WriteConcernError that occurred, or `null` if no write concern error occurred.
writeConcern
  The MongoDB\Driver\WriteConcern used for the bulk write, or `null` if not available.
errorReplies
  An array of error reply documents from the server.

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.

# MongoDB\Driver\WriteResult::getDeletedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getDeletedCount — Returns the number of documents deleted

### 説明

final public function MongoDB\Driver\WriteResult::getDeletedCount(): int

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the number of documents deleted.

### エラー / 例外

- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This method now throws an exception when called for an unacknowledged write instead of returning `null`.

### 例

例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

# MongoDB\Driver\WriteResult::getInsertedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getInsertedCount — Returns the number of documents inserted (excluding upserts)

### 説明

final public function MongoDB\Driver\WriteResult::getInsertedCount(): int

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the number of documents inserted (excluding upserts).

### エラー / 例外

- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This method now throws an exception when called for an unacknowledged write instead of returning `null`.

### 例

例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

# MongoDB\Driver\WriteResult::getMatchedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getMatchedCount — Returns the number of documents selected for update

### 説明

final public function 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.

### エラー / 例外

- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This method now throws an exception when called for an unacknowledged write instead of returning `null`.

### 例

例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

# MongoDB\Driver\WriteResult::getModifiedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getModifiedCount — Returns the number of existing documents updated

### 説明

final public function 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.

### エラー / 例外

- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This method now throws an exception when called for an unacknowledged write instead of returning `null`.

### 例

例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

# MongoDB\Driver\WriteResult::getServer

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getServer — Returns the server associated with this write result

### 説明

final public function 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();

    $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

# MongoDB\Driver\WriteResult::getUpsertedCount

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getUpsertedCount — Returns the number of documents inserted by an upsert

### 説明

final public function MongoDB\Driver\WriteResult::getUpsertedCount(): int

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the number of documents inserted by an upsert.

### エラー / 例外

- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This method now throws an exception when called for an unacknowledged write instead of returning `null`.

### 例

例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

# MongoDB\Driver\WriteResult::getUpsertedIds

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getUpsertedIds — Returns an array of identifiers for upserted documents

### 説明

final public function 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

# MongoDB\Driver\WriteResult::getWriteConcernError

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getWriteConcernError — Returns any write concern error that occurred

### 説明

final public function 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' => $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

# MongoDB\Driver\WriteResult::getWriteErrors

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::getWriteErrors — Returns any write errors that occurred

### 説明

final public function 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

# MongoDB\Driver\WriteResult::isAcknowledged

(mongodb >=1.0.0)

MongoDB\Driver\WriteResult::isAcknowledged — Returns whether the write was acknowledged

### 説明

final public function 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]);

    $writeConcern = new MongoDB\Driver\WriteConcern(0);

    $result = $manager->executeBulkWrite('db.collection', $bulk, ['writeConcern' => $writeConcern]);

    var_dump($result->isAcknowledged());

    ?>

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

    bool(false)

### 参考

- MongoDB\Driver\WriteConcern
- » Write Concern reference

## 目次

- 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\BulkWriteCommandResult class

(mongodb >=2.1.0)

## はじめに

The MongoDB\Driver\BulkWriteCommandResult class encapsulates information about an executed MongoDB\Driver\BulkWriteCommand and is returned by MongoDB\Driver\Manager::executeBulkWriteCommand().

## クラス概要

final class MongoDB\Driver\BulkWriteCommandResult {
/* メソッド */
final public function getDeletedCount(): int
final public function getDeleteResults(): ?MongoDB\BSON\Document
final public function getInsertedCount(): int
final public function getInsertResults(): ?MongoDB\BSON\Document
final public function getMatchedCount(): int
final public function getModifiedCount(): int
final public function getUpdateResults(): ?MongoDB\BSON\Document
final public function getUpsertedCount(): int
final public function isAcknowledged(): bool
}

# MongoDB\Driver\BulkWriteCommandResult::getDeletedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getDeletedCount — Returns the number of documents deleted

### 説明

final public function MongoDB\Driver\BulkWriteCommandResult::getDeletedCount(): int

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the total number of documents deleted by all operations.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.

### 例

例1 MongoDB\Driver\BulkWriteCommandResult::getDeletedCount() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getDeletedCount());

    ?>

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

    int(3)

### 参考

- MongoDB\Driver\BulkWriteCommandResult::getDeleteResults() - Returns verbose results for successful deletes
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Returns whether the write was acknowledged

# MongoDB\Driver\BulkWriteCommandResult::getDeleteResults

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getDeleteResults — Returns verbose results for successful deletes

### 説明

final public function MongoDB\Driver\BulkWriteCommandResult::getDeleteResults(): ?MongoDB\BSON\Document

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns a document containing the result of each successful delete operation, or `null` if verbose results were not requested. The document keys will correspond to the index of the write operation from MongoDB\Driver\BulkWriteCommand.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.

### 例

例1 MongoDB\Driver\BulkWriteCommandResult::getDeleteResults() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['verboseResults' => true]);
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getDeleteResults()->toPHP());

    ?>

上の例の出力は、 たとえば以下のようになります。

    object(stdClass)#7 (1) {
      ["4"]=>
      object(stdClass)#6 (1) {
        ["deletedCount"]=>
        object(MongoDB\BSON\Int64)#5 (1) {
          ["integer"]=>
          string(1) "3"
        }
      }
    }

### 参考

- MongoDB\Driver\BulkWriteCommandResult::getDeletedCount() - Returns the number of documents deleted
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Returns whether the write was acknowledged

# MongoDB\Driver\BulkWriteCommandResult::getInsertedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getInsertedCount — Returns the number of documents inserted

### 説明

final public function MongoDB\Driver\BulkWriteCommandResult::getInsertedCount(): int

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the total number of documents inserted (excluding upserts) by all operations.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.

### 例

例1 MongoDB\Driver\BulkWriteCommandResult::getInsertedCount() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getInsertedCount());

    ?>

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

    int(1)

### 参考

- MongoDB\Driver\BulkWriteCommandResult::getInsertResults() - Returns verbose results for successful inserts
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Returns whether the write was acknowledged

# MongoDB\Driver\BulkWriteCommandResult::getInsertResults

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getInsertResults — Returns verbose results for successful inserts

### 説明

final public function MongoDB\Driver\BulkWriteCommandResult::getInsertResults(): ?MongoDB\BSON\Document

Since `_id` fields for inserted documents are generated by the extension, the value of `insertedId` in each result will match the return value of MongoDB\Driver\BulkWriteCommand::insertOne() for the corresponding insert operation.

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns a document containing the result of each successful insert operation, or `null` if verbose results were not requested. The document keys will correspond to the index of the write operation from MongoDB\Driver\BulkWriteCommand.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.

### 例

例1 MongoDB\Driver\BulkWriteCommandResult::getInsertResults() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['verboseResults' => true]);

    $generatedId = $bulk->insertOne('db.coll', ['x' => 1]);

    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($generatedId);

    var_dump($result->getInsertResults()->toPHP());

    ?>

上の例の出力は、 たとえば以下のようになります。

    object(MongoDB\BSON\ObjectId)#3 (1) {
      ["oid"]=>
      string(24) "67f7ee69783dcce702097b41"
    }
    object(stdClass)#8 (1) {
      ["0"]=>
      object(stdClass)#7 (1) {
        ["insertedId"]=>
        object(MongoDB\BSON\ObjectId)#6 (1) {
          ["oid"]=>
          string(24) "67f7ee69783dcce702097b41"
        }
      }
    }

### 参考

- MongoDB\Driver\BulkWriteCommandResult::getInsertedCount() - Returns the number of documents inserted
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Returns whether the write was acknowledged
- MongoDB\Driver\BulkWriteCommand::insertOne() - Add an insertOne operation

# MongoDB\Driver\BulkWriteCommandResult::getMatchedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getMatchedCount — Returns the number of documents selected for update

### 説明

final public function MongoDB\Driver\BulkWriteCommandResult::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\BulkWriteCommandResult::getModifiedCount().

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the total number of documents selected for update by all operations.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.

### 例

例1 MongoDB\Driver\BulkWriteCommandResult::getMatchedCount() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getMatchedCount());

    ?>

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

    int(1)

### 参考

- MongoDB\Driver\BulkWriteCommandResult::getModifiedCount() - Returns the number of existing documents updated
- MongoDB\Driver\BulkWriteCommandResult::getUpdateResults() - Returns verbose results for successful updates
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Returns whether the write was acknowledged

# MongoDB\Driver\BulkWriteCommandResult::getModifiedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getModifiedCount — Returns the number of existing documents updated

### 説明

final public function MongoDB\Driver\BulkWriteCommandResult::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\BulkWriteCommandResult::getMatchedCount().

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the total number of existing documents updated by all operations.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.

### 例

例1 MongoDB\Driver\BulkWriteCommandResult::getModifiedCount() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getModifiedCount());

    ?>

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

    int(1)

### 参考

- MongoDB\Driver\BulkWriteCommandResult::getMatchedCount() - Returns the number of documents selected for update
- MongoDB\Driver\BulkWriteCommandResult::getUpdateResults() - Returns verbose results for successful updates
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Returns whether the write was acknowledged

# MongoDB\Driver\BulkWriteCommandResult::getUpdateResults

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getUpdateResults — Returns verbose results for successful updates

### 説明

final public function MongoDB\Driver\BulkWriteCommandResult::getUpdateResults(): ?MongoDB\BSON\Document

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns a document containing the result of each successful update operation, or `null` if verbose results were not requested. The document keys will correspond to the index of the write operation from MongoDB\Driver\BulkWriteCommand.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.

### 例

例1 MongoDB\Driver\BulkWriteCommandResult::getUpdateResults() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['verboseResults' => true]);
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getUpdateResults()->toPHP());

    ?>

上の例の出力は、 たとえば以下のようになります。

    object(stdClass)#16 (3) {
      ["1"]=>
      object(stdClass)#7 (2) {
        ["matchedCount"]=>
        object(MongoDB\BSON\Int64)#5 (1) {
          ["integer"]=>
          string(1) "1"
        }
        ["modifiedCount"]=>
        object(MongoDB\BSON\Int64)#6 (1) {
          ["integer"]=>
          string(1) "1"
        }
      }
      ["2"]=>
      object(stdClass)#11 (3) {
        ["matchedCount"]=>
        object(MongoDB\BSON\Int64)#8 (1) {
          ["integer"]=>
          string(1) "1"
        }
        ["modifiedCount"]=>
        object(MongoDB\BSON\Int64)#9 (1) {
          ["integer"]=>
          string(1) "0"
        }
        ["upsertedId"]=>
        object(MongoDB\BSON\ObjectId)#10 (1) {
          ["oid"]=>
          string(24) "67f7eb9b1f198bbcb880d575"
        }
      }
      ["3"]=>
      object(stdClass)#15 (3) {
        ["matchedCount"]=>
        object(MongoDB\BSON\Int64)#12 (1) {
          ["integer"]=>
          string(1) "1"
        }
        ["modifiedCount"]=>
        object(MongoDB\BSON\Int64)#13 (1) {
          ["integer"]=>
          string(1) "0"
        }
        ["upsertedId"]=>
        object(MongoDB\BSON\ObjectId)#14 (1) {
          ["oid"]=>
          string(24) "67f7eb9b1f198bbcb880d576"
        }
      }
    }

### 参考

- MongoDB\Driver\BulkWriteCommandResult::getMatchedCount() - Returns the number of documents selected for update
- MongoDB\Driver\BulkWriteCommandResult::getModifiedCount() - Returns the number of existing documents updated
- MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount() - Returns the number of documents upserted
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Returns whether the write was acknowledged

# MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount — Returns the number of documents upserted

### 説明

final public function MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount(): int

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the total number of documents upserted by all operations.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\LogicException if the write was not acknowledged.

### 例

例1 MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);
    $bulk->updateOne('db.coll', ['x' => 1], ['$set' => ['y' => 3]]);
    $bulk->updateOne('db.coll', ['x' => 2], ['$set' => ['y' => 1]], ['upsert' => true]);
    $bulk->updateOne('db.coll', ['x' => 3], ['$set' => ['y' => 2]], ['upsert' => true]);
    $bulk->deleteMany('db.coll', []);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->getUpsertedCount());

    ?>

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

    int(2)

### 参考

- MongoDB\Driver\BulkWriteCommandResult::getUpdateResults() - Returns verbose results for successful updates
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() - Returns whether the write was acknowledged

# MongoDB\Driver\BulkWriteCommandResult::isAcknowledged

(mongodb >=2.1.0)

MongoDB\Driver\BulkWriteCommandResult::isAcknowledged — Returns whether the write was acknowledged

### 説明

final public function MongoDB\Driver\BulkWriteCommandResult::isAcknowledged(): bool

If the write is acknowledged, other fields will be available on the MongoDB\Driver\BulkWriteCommandResult object.

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns `true` if the write was acknowledged, and `false` otherwise.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 例

例1 MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() with acknowledged write concern

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);

    $result = $manager->executeBulkWriteCommand($bulk);

    var_dump($result->isAcknowledged());

    ?>

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

    bool(true)

例2 MongoDB\Driver\BulkWriteCommandResult::isAcknowledged() with unacknowledged write concern

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['ordered' => false]);
    $bulk->insertOne('db.coll', ['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(0);

    $result = $manager->executeBulkWriteCommand($bulk, ['writeConcern' => $writeConcern]);

    var_dump($result->isAcknowledged());

    ?>

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

    bool(false)

### 参考

- MongoDB\Driver\WriteConcern
- » Write Concern reference

## 目次

- MongoDB\Driver\BulkWriteCommandResult::getDeletedCount — Returns the number of documents deleted
- MongoDB\Driver\BulkWriteCommandResult::getDeleteResults — Returns verbose results for successful deletes
- MongoDB\Driver\BulkWriteCommandResult::getInsertedCount — Returns the number of documents inserted
- MongoDB\Driver\BulkWriteCommandResult::getInsertResults — Returns verbose results for successful inserts
- MongoDB\Driver\BulkWriteCommandResult::getMatchedCount — Returns the number of documents selected for update
- MongoDB\Driver\BulkWriteCommandResult::getModifiedCount — Returns the number of existing documents updated
- MongoDB\Driver\BulkWriteCommandResult::getUpdateResults — Returns verbose results for successful updates
- MongoDB\Driver\BulkWriteCommandResult::getUpsertedCount — Returns the number of documents upserted
- MongoDB\Driver\BulkWriteCommandResult::isAcknowledged — Returns whether the write was acknowledged

# MongoDB BSON Classes and Functions

## 目次

- 関数
- MongoDB\BSON\Document
- MongoDB\BSON\PackedArray
- MongoDB\BSON\Iterator
- MongoDB\BSON\Binary
- MongoDB\BSON\VectorType
- MongoDB\BSON\Decimal128
- MongoDB\BSON\Javascript
- MongoDB\BSON\MaxKey
- MongoDB\BSON\MinKey
- MongoDB\BSON\ObjectId
- MongoDB\BSON\Regex
- MongoDB\BSON\Timestamp
- MongoDB\BSON\UTCDateTime
- MongoDB\BSON\Type
- MongoDB\BSON\Persistable
- MongoDB\BSON\Serializable
- MongoDB\BSON\Unserializable
- MongoDB\BSON\BinaryInterface
- MongoDB\BSON\Decimal128Interface
- MongoDB\BSON\JavascriptInterface
- MongoDB\BSON\MaxKeyInterface
- MongoDB\BSON\MinKeyInterface
- MongoDB\BSON\ObjectIdInterface
- MongoDB\BSON\RegexInterface
- MongoDB\BSON\TimestampInterface
- MongoDB\BSON\UTCDateTimeInterface
- MongoDB\BSON\DBPointer
- MongoDB\BSON\Int64
- MongoDB\BSON\Symbol
- MongoDB\BSON\Undefined

# 関数

# MongoDB\BSON\fromJSON

(mongodb >=1.0.0)

MongoDB\BSON\fromJSON — Returns the BSON representation of a JSON value

警告

This function has been DEPRECATED as of extension version 1.20.0 and was removed in 2.0. Applications should use MongoDB\BSON\Document::fromJSON() instead.

### 説明

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

### 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This function was removed.

### 例

例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

# MongoDB\BSON\fromPHP

(mongodb >=1.0.0)

MongoDB\BSON\fromPHP — Returns the BSON representation of a PHP value

警告

This function has been DEPRECATED as of extension version 1.20.0 and was removed in 2.0. Applications should use MongoDB\BSON\Document::fromPHP() instead.

### 説明

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

### 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This function was removed.

### 例

例1 MongoDB\BSON\fromPHP() example

    <?php

    $bson = MongoDB\BSON\fromPHP(['foo' => 1]);
    echo bin2hex($bson), "\n";

    ?>

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

    0e00000010666f6f000100000000

### 参考

- 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

# MongoDB\BSON\toCanonicalExtendedJSON

(mongodb >=1.3.0)

MongoDB\BSON\toCanonicalExtendedJSON — Returns the Canonical Extended JSON representation of a BSON value

警告

This function has been DEPRECATED as of extension version 1.20.0 and was removed in 2.0. Applications should use MongoDB\BSON\Document::toCanonicalExtendedJSON() instead.

### 説明

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

### 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This function was removed.

### 例

例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

# MongoDB\BSON\toJSON

(mongodb >=1.0.0)

MongoDB\BSON\toJSON — Returns the Legacy Extended JSON representation of a BSON value

警告

This function has been DEPRECATED as of extension version 1.20.0 and was removed in 2.0. Applications should use MongoDB\BSON\Document::toCanonicalExtendedJSON() or MongoDB\BSON\Document::toRelaxedExtendedJSON() instead.

### 説明

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

### 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This function was removed.

### 例

例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

# MongoDB\BSON\toPHP

(mongodb >=1.0.0)

MongoDB\BSON\toPHP — Returns the PHP representation of a BSON value

警告

This function has been DEPRECATED as of extension version 1.20.0 and was removed in 2.0. Applications should use MongoDB\BSON\Document::toPHP() instead.

### 説明

function 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 2.0.0 | This function was removed.
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

# MongoDB\BSON\toRelaxedExtendedJSON

(mongodb >=1.3.0)

MongoDB\BSON\toRelaxedExtendedJSON — Returns the Relaxed Extended JSON representation of a BSON value

警告

This function has been DEPRECATED as of extension version 1.20.0 and was removed in 2.0. Applications should use MongoDB\BSON\Document::toRelaxedExtendedJSON() instead.

### 説明

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

### 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This function was removed.

### 例

例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

## 目次

- 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

# 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 {
/* メソッド */
final private function __construct()
final static public function fromBSON(string `$bson`): MongoDB\BSON\Document
final static public function fromJSON(string `$json`): MongoDB\BSON\Document
final static public function fromPHP(object|array `$value`): MongoDB\BSON\Document
final public function get(string `$key`): mixed
final public function getIterator(): MongoDB\BSON\Iterator
final public function has(string `$key`): bool
final public function offsetExists(mixed `$key`): bool
final public function offsetGet(mixed `$key`): mixed
final public function offsetSet(mixed `$key`, mixed `$value`): void
final public function offsetUnset(mixed `$key`): void
final public function toCanonicalExtendedJSON(): string
final public function toPHP(?array `$typeMap` = `null`): array|object
final public function toRelaxedExtendedJSON(): string
final public function __toString(): string
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This class no longer implements the Serializable interface.
PECL mongodb 1.17.0 | Implements MongoDB\BSON\Type.

# MongoDB\BSON\Document::__construct

(mongodb >=1.16.0)

MongoDB\BSON\Document::__construct — Construct a new BSON document (unused)

### 説明

final private function 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

# MongoDB\BSON\Document::fromBSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::fromBSON — Construct a new document instance from a BSON string

### 説明

final static public function MongoDB\BSON\Document::fromBSON(string `$bson`): MongoDB\BSON\Document

### パラメータ

`bson` (string)
  A string containing a document in BSON format.

### 戻り値

Returns a new MongoDB\BSON\Document instance.

### エラー / 例外

- 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

# MongoDB\BSON\Document::fromJSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::fromJSON — Construct a new document instance from a JSON string

### 説明

final static public function 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.

### 戻り値

Returns a new MongoDB\BSON\Document instance.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\UnexpectedValueException if the JSON value cannot be converted to a BSON document (e.g. due to a syntax error).

### 参考

- 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 Extended JSON
- » BSON Types

# MongoDB\BSON\Document::fromPHP

(mongodb >=1.16.0)

MongoDB\BSON\Document::fromPHP — Construct a new document instance from PHP data

### 説明

final static public function 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.

### 戻り値

Returns a new MongoDB\BSON\Document instance.

### エラー / 例外

- 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
- » BSON Types

# MongoDB\BSON\Document::get

(mongodb >=1.16.0)

MongoDB\BSON\Document::get — Returns the value of a key in the document

### 説明

final public function 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

# MongoDB\BSON\Document::getIterator

(mongodb >=1.16.0)

MongoDB\BSON\Document::getIterator — Returns an iterator for the BSON document

### 説明

final public function 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

# MongoDB\BSON\Document::has

(mongodb >=1.16.0)

MongoDB\BSON\Document::has — Returns whether a key is present in the document

### 説明

final public function 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

# MongoDB\BSON\Document::offsetExists

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetExists — Returns whether a key is present in the document

### 説明

final public function 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

# MongoDB\BSON\Document::offsetGet

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetGet — Returns the value of a key in the document

### 説明

final public function 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

# MongoDB\BSON\Document::offsetSet

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetSet — Implementation of ArrayAccess

### 説明

final public function 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.

# MongoDB\BSON\Document::offsetUnset

(mongodb >=1.17.0)

MongoDB\BSON\Document::offsetUnset — Implementation of ArrayAccess

### 説明

final public function 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.

# MongoDB\BSON\Document::toCanonicalExtendedJSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::toCanonicalExtendedJSON — Returns the Canonical Extended JSON representation of the BSON document

### 説明

final public function 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).

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns a string containing the » Canonical Extended JSON representation of the BSON document.

### 例

例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

# MongoDB\BSON\Document::toPHP

(mongodb >=1.16.0)

MongoDB\BSON\Document::toPHP — Returns the PHP representation of the BSON document

### 説明

final public function 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

# MongoDB\BSON\Document::toRelaxedExtendedJSON

(mongodb >=1.16.0)

MongoDB\BSON\Document::toRelaxedExtendedJSON — Returns the Relaxed Extended JSON representation of the BSON document

### 説明

final public function 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.

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns a string containing the » Relaxed Extended JSON representation of the BSON document.

### 例

例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

# MongoDB\BSON\Document::__toString

(mongodb >=1.16.0)

MongoDB\BSON\Document::__toString — Returns the string representation of this BSON Document

### 説明

final public function MongoDB\BSON\Document::__toString(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the string representation of this document as BSON.

### 参考

- » BSON Types

## 目次

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

# 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 {
/* メソッド */
final private function __construct()
final static public function fromJSON(string `$json`): MongoDB\BSON\PackedArray
final static public function fromPHP(array `$value`): MongoDB\BSON\PackedArray
final public function get(int `$key`): mixed
final public function getIterator(): MongoDB\BSON\Iterator
final public function has(int `$index`): bool
final public function offsetExists(mixed `$key`): bool
final public function offsetGet(mixed `$key`): mixed
final public function offsetSet(mixed `$key`, mixed `$value`): void
final public function offsetUnset(mixed `$key`): void
final public function toCanonicalExtendedJSON(): string
final public function toPHP(?array `$typeMap` = `null`): array|object
final public function toRelaxedExtendedJSON(): string
final public function __toString(): string
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This class no longer implements the Serializable interface.
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

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::__construct — Construct a new BSON array (unused)

### 説明

final private function 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

# MongoDB\BSON\PackedArray::fromJSON

(mongodb >=1.20.0)

MongoDB\BSON\PackedArray::fromJSON — Construct a new BSON array instance from a JSON string

### 説明

final static public function MongoDB\BSON\PackedArray::fromJSON(string `$json`): MongoDB\BSON\PackedArray

Converts an » extended JSON string to its BSON representation.

### パラメータ

`json` (string)
  JSON value to be converted.

### 戻り値

Returns a new MongoDB\BSON\PackedArray instance.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.
- Throws MongoDB\Driver\Exception\UnexpectedValueException if the JSON value cannot be converted to a BSON array (e.g. due to a syntax error).

### 例

例1 MongoDB\BSON\PackedArray::fromJSON() example

    <?php

    $json = '[ "foo", { "$numberInt" : "123" }, { "$numberLong" : "4294967295" }, { "$oid" : "56315a7c6118fd1b920270b1" } ]';
    $packedArray = MongoDB\BSON\PackedArray::fromJSON($json);
    var_dump($packedArray);

    ?>

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

    object(MongoDB\BSON\PackedArray)#1 (2) {
      ["data"]=>
      string(68) "MQAAAAIwAAQAAABmb28AEDEAewAAABIyAP////8AAAAABzMAVjFafGEY/RuSAnCxAA=="
      ["value"]=>
      array(4) {
        [0]=>
        string(3) "foo"
        [1]=>
        int(123)
        [2]=>
        int(4294967295)
        [3]=>
        object(MongoDB\BSON\ObjectId)#2 (1) {
          ["oid"]=>
          string(24) "56315a7c6118fd1b920270b1"
        }
      }
    }

### 参考

- MongoDB\BSON\PackedArray::fromPHP() - Construct a new BSON array instance from PHP data
- » MongoDB Extended JSON
- » BSON Types

# MongoDB\BSON\PackedArray::fromPHP

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::fromPHP — Construct a new BSON array instance from PHP data

### 説明

final static public function 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`).

### 戻り値

Returns a new MongoDB\BSON\PackedArray instance.

### エラー / 例外

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

### 参考

- » BSON Types

# MongoDB\BSON\PackedArray::get

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::get — Returns the value of an index in the array

### 説明

final public function 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

# MongoDB\BSON\PackedArray::getIterator

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::getIterator — Returns an iterator for the BSON array

### 説明

final public function 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

# MongoDB\BSON\PackedArray::has

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::has — Returns whether a index is present in the array

### 説明

final public function 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

# MongoDB\BSON\PackedArray::offsetExists

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetExists — Returns whether a index is present in the array

### 説明

final public function 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

# MongoDB\BSON\PackedArray::offsetGet

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetGet — Returns the value of an index in the array

### 説明

final public function 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

# MongoDB\BSON\PackedArray::offsetSet

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetSet — Implementation of ArrayAccess

### 説明

final public function 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.

# MongoDB\BSON\PackedArray::offsetUnset

(mongodb >=1.17.0)

MongoDB\BSON\PackedArray::offsetUnset — Implementation of ArrayAccess

### 説明

final public function 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.

# MongoDB\BSON\PackedArray::toCanonicalExtendedJSON

(mongodb >=1.20.0)

MongoDB\BSON\PackedArray::toCanonicalExtendedJSON — Returns the Canonical Extended JSON representation of the BSON array

### 説明

final public function MongoDB\BSON\PackedArray::toCanonicalExtendedJSON(): string

Converts the BSON array 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).

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns a string containing the » Canonical Extended JSON representation of the BSON array.

### 例

例1 MongoDB\BSON\PackedArray::toCanonicalExtendedJSON() example

    <?php

    $array = [
        'foo',
        123,
        4294967295,
        new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1'),
    ];

    $packedArray = MongoDB\BSON\PackedArray::fromPHP($array);
    echo $packedArray->toCanonicalExtendedJSON(), "\n";

    ?>

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

    [ "foo", { "$numberInt" : "123" }, { "$numberLong" : "4294967295" }, { "$oid" : "56315a7c6118fd1b920270b1" } ]

### 参考

- MongoDB\BSON\PackedArray::fromJSON() - Construct a new BSON array instance from a JSON string
- MongoDB\BSON\PackedArray::toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of the BSON array
- MongoDB\BSON\toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of a BSON value
- » Extended JSON Specification
- » BSON Types

# MongoDB\BSON\PackedArray::toPHP

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::toPHP — Returns the PHP representation of the BSON array

### 説明

final public function 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

# MongoDB\BSON\PackedArray::toRelaxedExtendedJSON

(mongodb >=1.20.0)

MongoDB\BSON\PackedArray::toRelaxedExtendedJSON — Returns the Relaxed Extended JSON representation of the BSON array

### 説明

final public function MongoDB\BSON\PackedArray::toRelaxedExtendedJSON(): string

Converts the BSON array 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.

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns a string containing the » Relaxed Extended JSON representation of the BSON array.

### 例

例1 MongoDB\BSON\PackedArray::toRelaxedExtendedJSON() example

    <?php

    $array = [
        'foo',
        123,
        4294967295,
        new MongoDB\BSON\ObjectId('56315a7c6118fd1b920270b1'),
    ];

    $packedArray = MongoDB\BSON\PackedArray::fromPHP($array);
    echo $packedArray->toRelaxedExtendedJSON(), "\n";

    ?>

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

    [ "foo", 123, 4294967295, { "$oid" : "56315a7c6118fd1b920270b1" } ]

### 参考

- MongoDB\BSON\PackedArray::fromJSON() - Construct a new BSON array instance from a JSON string
- MongoDB\BSON\PackedArray::toCanonicalExtendedJSON() - Returns the Canonical Extended JSON representation of the BSON array
- MongoDB\BSON\toRelaxedExtendedJSON() - Returns the Relaxed Extended JSON representation of a BSON value
- » Extended JSON Specification
- » BSON Types

# MongoDB\BSON\PackedArray::__toString

(mongodb >=1.16.0)

MongoDB\BSON\PackedArray::__toString — Returns the string representation of this BSON array

### 説明

final public function MongoDB\BSON\PackedArray::__toString(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the string representation of this array as BSON.

### 参考

- » BSON Types

## 目次

- MongoDB\BSON\PackedArray::__construct — Construct a new BSON array (unused)
- MongoDB\BSON\PackedArray::fromJSON — Construct a new BSON array instance from a JSON string
- 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::toCanonicalExtendedJSON — Returns the Canonical Extended JSON representation of the BSON array
- MongoDB\BSON\PackedArray::toPHP — Returns the PHP representation of the BSON array
- MongoDB\BSON\PackedArray::toRelaxedExtendedJSON — Returns the Relaxed Extended JSON representation of the BSON array
- MongoDB\BSON\PackedArray::__toString — Returns the string representation of this BSON array

# 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 function __construct()
public function current(): mixed
public function key(): string|int
public function next(): void
public function rewind(): void
public function valid(): bool
}

# MongoDB\BSON\Iterator::__construct

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::__construct — Construct a new BSON iterator (unused)

### 説明

final private function 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

# MongoDB\BSON\Iterator::current

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::current — Returns the current element

### 説明

public function 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() - 現在の要素を返す

# MongoDB\BSON\Iterator::key

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::key — Returns the key of the current element

### 説明

public function 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() - 現在の要素のキーを返す

# MongoDB\BSON\Iterator::next

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::next — Advances the iterator to next element

### 説明

public function MongoDB\BSON\Iterator::next(): void

### パラメータ

この関数にはパラメータはありません。

### 参考

- Iterator::next() - 次の要素に進む

# MongoDB\BSON\Iterator::rewind

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::rewind — Rewinds the Iterator to the first element

### 説明

public function MongoDB\BSON\Iterator::rewind(): void

### パラメータ

この関数にはパラメータはありません。

### 参考

- Iterator::rewind() - イテレータの最初の要素に巻き戻す

# MongoDB\BSON\Iterator::valid

(mongodb >=1.16.0)

MongoDB\BSON\Iterator::valid — Checks if current position is valid

### 説明

public function MongoDB\BSON\Iterator::valid(): bool

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns `true` if the current iterator position is valid, `false` otherwise.

### 参考

- Iterator::valid() - 現在位置が有効かどうかを調べる

## 目次

- 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

# 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, 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_VECTOR = 9;
const int TYPE_USER_DEFINED = 128;
/* メソッド */
final public function __construct(string `$data`, int `$type` = MongoDB\BSON\Binary::TYPE_GENERIC)
final public static function fromVector(array `$vector`, MongoDB\BSON\VectorType `$vectorType`): MongoDB\BSON\Binary
final public function getData(): string
final public function getType(): int
final public function getVectorType(): MongoDB\BSON\VectorType
final public function jsonSerialize(): mixed
final public function toArray(): array
final public function __toString(): string
}

## 定義済み定数

`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_VECTOR`
  Vector data. This subtype is used to efficiently store vector data for use with MongoDB's vector search.
`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 2.2.0 | Added `MongoDB\BSON\Binary::TYPE_VECTOR`, as well as the MongoDB\BSON\Binary::fromVector(), MongoDB\BSON\Binary::getVectorType(), and MongoDB\BSON\Binary::toArray() functions.
PECL mongodb 2.0.0 | This class no longer implements the Serializable interface.
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

(mongodb >=1.0.0)

MongoDB\BSON\Binary::__construct — Construct a new Binary

### 説明

final public function 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

# MongoDB\BSON\Binary::fromVector

(mongodb >=2.2.0)

MongoDB\BSON\Binary::fromVector — Creates a new binary with subtype `MongoDB\BSON\Binary::SUBTYPE_VECTOR` from the given array and vector type

### 説明

final public static function MongoDB\BSON\Binary::fromVector(array `$vector`, MongoDB\BSON\VectorType `$vectorType`): MongoDB\BSON\Binary

### パラメータ

`vector` (array)

  An array of values representing the vector data. The type of each value must match the type indicated by the `vectorType` parameter:

  - for `MongoDB\BSON\VectorType::Float32`, each value must be a float
  - for `MongoDB\BSON\VectorType::Int8`, each value must be an 8-bit int, i.e. from `-127` to `128`
  - for `MongoDB\BSON\VectorType::PackedBit`, each value must be a bool or 1-bit int, i.e. `0` or `1`
`vectorType` (MongoDB\BSON\VectorType)
  The vector data type.

### 戻り値

Returns a new Binary with subtype `MongoDB\BSON\Binary::SUBTYPE_VECTOR`.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参考

- MongoDB\BSON\Binary::toArray() - Returns the vector as an array for a Binary with subtype MongoDB\BSON\Binary::SUBTYPE_VECTOR
- MongoDB\BSON\Binary::getVectorType() - Returns the data type for a Binary with the vector subtype
- MongoDB\BSON\VectorType
- » BSON Types

# MongoDB\BSON\Binary::getData

(mongodb >=1.0.0)

MongoDB\BSON\Binary::getData — Returns the Binary's data

### 説明

final public function 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

# MongoDB\BSON\Binary::getType

(mongodb >=1.0.0)

MongoDB\BSON\Binary::getType — Returns the Binary's type

### 説明

final public function 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

# MongoDB\BSON\Binary::getVectorType

(mongodb >=2.2.0)

MongoDB\BSON\Binary::getVectorType — Returns the data type for a Binary with the vector subtype

### 説明

final public function MongoDB\BSON\Binary::getVectorType(): MongoDB\BSON\VectorType

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the data type of the Binary vector.

### エラー / 例外

- Throws MongoDB\Driver\Exception\LogicException if the subtype is not `MongoDB\BSON\Binary::SUBTYPE_VECTOR`.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参考

- » BSON Types
- MongoDB\BSON\VectorType

# MongoDB\BSON\Binary::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Binary::jsonSerialize — Returns a representation that can be converted to JSON

### 説明

final public function 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

# MongoDB\BSON\Binary::toArray

(mongodb >=2.2.0)

MongoDB\BSON\Binary::toArray — Returns the vector as an array for a Binary with subtype `MongoDB\BSON\Binary::SUBTYPE_VECTOR`

### 説明

final public function MongoDB\BSON\Binary::toArray(): array

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns an array containing the vector data.

### エラー / 例外

- Throws MongoDB\Driver\Exception\LogicException if the subtype is not `MongoDB\BSON\Binary::SUBTYPE_VECTOR`.
- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

### 参考

- MongoDB\BSON\Binary::fromVector() - Creates a new binary with subtype MongoDB\BSON\Binary::SUBTYPE_VECTOR from the given array and vector type
- » BSON Types

# MongoDB\BSON\Binary::__toString

(mongodb >=1.2.0)

MongoDB\BSON\Binary::__toString — Returns the Binary's data

### 説明

final public function 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

## 目次

- MongoDB\BSON\Binary::__construct — Construct a new Binary
- MongoDB\BSON\Binary::fromVector — Creates a new binary with subtype MongoDB\BSON\Binary::SUBTYPE_VECTOR from the given array and vector type
- MongoDB\BSON\Binary::getData — Returns the Binary's data
- MongoDB\BSON\Binary::getType — Returns the Binary's type
- MongoDB\BSON\Binary::getVectorType — Returns the data type for a Binary with the vector subtype
- MongoDB\BSON\Binary::jsonSerialize — Returns a representation that can be converted to JSON
- MongoDB\BSON\Binary::toArray — Returns the vector as an array for a Binary with subtype MongoDB\BSON\Binary::SUBTYPE_VECTOR
- MongoDB\BSON\Binary::__toString — Returns the Binary's data

# The MongoDB\BSON\VectorType enum

(mongodb >=2.2.0)

## はじめに

The MongoDB\BSON\VectorType enum is used to specify the type of vector data stored in a MongoDB\BSON\Binary with subtype `MongoDB\BSON\Binary::TYPE_VECTOR`.

## 列挙型概要

enum MongoDB\BSON\VectorType
{
case Float32 ; // Each element in the vector is a 32-bit floating point value.
case Int8 ; // Each element in the vector is an 8-bit integer value.
case PackedBit ; // Each element in the vector is a 1-bit value. When creating vectors of this type, you may pass either bool or 1-bit int values, i.e. `0` or `1`.
}

# 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, JsonSerializable, Stringable {
/* メソッド */
final public function __construct(string `$value`)
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This class no longer implements the Serializable interface.
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

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::__construct — Construct a new Decimal128

### 説明

final public function 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

# MongoDB\BSON\Decimal128::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::jsonSerialize — Returns a representation that can be converted to JSON

### 説明

final public function 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

# MongoDB\BSON\Decimal128::__toString

(mongodb >=1.2.0)

MongoDB\BSON\Decimal128::__toString — Returns the string representation of this Decimal128

### 説明

final public function 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

## 目次

- MongoDB\BSON\Decimal128::__construct — Construct a new Decimal128
- MongoDB\BSON\Decimal128::jsonSerialize — Returns a representation that can be converted to JSON
- MongoDB\BSON\Decimal128::__toString — Returns the string representation of this Decimal128

# 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, JsonSerializable, Stringable {
/* メソッド */
final public function __construct(string `$code`, array|object|null `$scope` = `null`)
final public function getCode(): string
final public function getScope(): ?object
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This class no longer implements the Serializable interface.
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

(mongodb >=1.0.0)

MongoDB\BSON\Javascript::__construct — Construct a new Javascript

### 説明

final public function 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

# MongoDB\BSON\Javascript::getCode

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::getCode — Returns the Javascript's code

### 説明

final public function 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

# MongoDB\BSON\Javascript::getScope

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::getScope — Returns the Javascript's scope document

### 説明

final public function 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

# MongoDB\BSON\Javascript::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::jsonSerialize — Returns a representation that can be converted to JSON

### 説明

final public function 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

# MongoDB\BSON\Javascript::__toString

(mongodb >=1.2.0)

MongoDB\BSON\Javascript::__toString — Returns the Javascript's code

### 説明

final public function 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

## 目次

- 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::__toString — Returns the Javascript's code

# 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, JsonSerializable {
/* メソッド */
final public function __construct()
final public function jsonSerialize(): mixed
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This class no longer implements the Serializable interface.
PECL mongodb 1.3.0 | Implements MongoDB\BSON\MaxKeyInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

# MongoDB\BSON\MaxKey::__construct

(mongodb >=1.0.0)

MongoDB\BSON\MaxKey::__construct — Construct a new MaxKey

### 説明

final public function 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

# MongoDB\BSON\MaxKey::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\MaxKey::jsonSerialize — Returns a representation that can be converted to JSON

### 説明

final public function 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

## 目次

- MongoDB\BSON\MaxKey::__construct — Construct a new MaxKey
- MongoDB\BSON\MaxKey::jsonSerialize — Returns a representation that can be converted to JSON

# 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, JsonSerializable {
/* メソッド */
final public function __construct()
final public function jsonSerialize(): mixed
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This class no longer implements the Serializable interface.
PECL mongodb 1.3.0 | Implements MongoDB\BSON\MinKeyInterface.
PECL mongodb 1.2.0 | Implements Serializable and JsonSerializable.

# MongoDB\BSON\MinKey::__construct

(mongodb >=1.0.0)

MongoDB\BSON\MinKey::__construct — Construct a new MinKey

### 説明

final public function 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

# MongoDB\BSON\MinKey::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\MinKey::jsonSerialize — Returns a representation that can be converted to JSON

### 説明

final public function 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

## 目次

- MongoDB\BSON\MinKey::__construct — Construct a new MinKey
- MongoDB\BSON\MinKey::jsonSerialize — Returns a representation that can be converted to JSON

# 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, JsonSerializable, Stringable {
/* メソッド */
final public function __construct(?string `$id` = `null`)
final public function getTimestamp(): int
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This class no longer implements the Serializable interface.
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

(mongodb >=1.0.0)

MongoDB\BSON\ObjectId::__construct — Construct a new ObjectId

### 説明

final public function 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

# MongoDB\BSON\ObjectId::getTimestamp

(mongodb >=1.2.0)

MongoDB\BSON\ObjectId::getTimestamp — Returns the timestamp component of this ObjectId

### 説明

final public function 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

# MongoDB\BSON\ObjectId::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\ObjectId::jsonSerialize — Returns a representation that can be converted to JSON

### 説明

final public function 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

# MongoDB\BSON\ObjectId::__toString

(mongodb >=1.0.0)

MongoDB\BSON\ObjectId::__toString — Returns the hexidecimal representation of this ObjectId

### 説明

final public function 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

## 目次

- 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::__toString — Returns the hexidecimal representation of this ObjectId

# 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, JsonSerializable, Stringable {
/* メソッド */
final public function __construct(string `$pattern`, string `$flags` = "")
final public function getFlags(): string
final public function getPattern(): string
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This class no longer implements the Serializable interface.
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

(mongodb >=1.0.0)

MongoDB\BSON\Regex::__construct — Construct a new Regex

### 説明

final public function 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

# MongoDB\BSON\Regex::getFlags

(mongodb >=1.0.0)

MongoDB\BSON\Regex::getFlags — Returns the Regex's flags

### 説明

final public function 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

# MongoDB\BSON\Regex::getPattern

(mongodb >=1.0.0)

MongoDB\BSON\Regex::getPattern — Returns the Regex's pattern

### 説明

final public function 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

# MongoDB\BSON\Regex::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Regex::jsonSerialize — Returns a representation that can be converted to JSON

### 説明

final public function 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

# MongoDB\BSON\Regex::__toString

(mongodb >=1.0.0)

MongoDB\BSON\Regex::__toString — Returns the string representation of this Regex

### 説明

final public function 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

## 目次

- 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::__toString — Returns the string representation of this Regex

# 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, JsonSerializable, Stringable {
/* メソッド */
final public function __construct(int `$increment`, int `$timestamp`)
final public function getIncrement(): int
final public function getTimestamp(): int
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This class no longer implements the Serializable interface.
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

(mongodb >=1.0.0)

MongoDB\BSON\Timestamp::__construct — Construct a new Timestamp

### 説明

final public function 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

# MongoDB\BSON\Timestamp::getIncrement

(mongodb >=1.3.0)

MongoDB\BSON\Timestamp::getIncrement — Returns the increment component of this Timestamp

### 説明

final public function 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

# MongoDB\BSON\Timestamp::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\Timestamp::getTimestamp — Returns the timestamp component of this Timestamp

### 説明

final public function 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

# MongoDB\BSON\Timestamp::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\Timestamp::jsonSerialize — Returns a representation that can be converted to JSON

### 説明

final public function 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

# MongoDB\BSON\Timestamp::__toString

(mongodb >=1.0.0)

MongoDB\BSON\Timestamp::__toString — Returns the string representation of this Timestamp

### 説明

final public function 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

## 目次

- 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::__toString — Returns the string representation of this Timestamp

# 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, JsonSerializable, Stringable {
/* メソッド */
final public function __construct(int|MongoDB\BSON\Int64|DateTimeInterface|null `$milliseconds` = `null`)
final public function jsonSerialize(): mixed
final public function toDateTime(): DateTime
final public function toDateTimeImmutable(): DateTimeImmutable
final public function __toString(): string
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This class no longer implements the Serializable interface.
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

(mongodb >=1.0.0)

MongoDB\BSON\UTCDateTime::__construct — Construct a new UTCDateTime

### 説明

final public function MongoDB\BSON\UTCDateTime::__construct(int|MongoDB\BSON\Int64|DateTimeInterface|null `$milliseconds` = `null`)

### パラメータ

`milliseconds` (int|MongoDB\BSON\Int64|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 MongoDB\BSON\Int64. 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 2.0.0 | The `milliseconds` no longer accepts a string or float argument.
PECL mongodb 1.20.0 | The `milliseconds` argument now accepts a MongoDB\BSON\Int64 object (for compatibility on 32-bit platforms). Specifying a string or float is deprecated.
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

# MongoDB\BSON\UTCDateTime::jsonSerialize

(mongodb >=1.2.0)

MongoDB\BSON\UTCDateTime::jsonSerialize — Returns a representation that can be converted to JSON

### 説明

final public function 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

# MongoDB\BSON\UTCDateTime::toDateTime

(mongodb >=1.0.0)

MongoDB\BSON\UTCDateTime::toDateTime — Returns the DateTime representation of this UTCDateTime

### 説明

final public function 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

# MongoDB\BSON\UTCDateTime::toDateTimeImmutable

(mongodb >=1.20.0)

MongoDB\BSON\UTCDateTime::toDateTimeImmutable — Returns the DateTimeImmutable representation of this UTCDateTime

### 説明

final public function 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

# MongoDB\BSON\UTCDateTime::__toString

(mongodb >=1.0.0)

MongoDB\BSON\UTCDateTime::__toString — Returns the string representation of this UTCDateTime

### 説明

final public function 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

## 目次

- MongoDB\BSON\UTCDateTime::__construct — Construct a new UTCDateTime
- MongoDB\BSON\UTCDateTime::jsonSerialize — Returns a representation that can be converted to JSON
- 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

# 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 function bsonSerialize(): array|stdClass|MongoDB\BSON\Document
/* 継承したメソッド */
abstract public function MongoDB\BSON\Serializable::bsonSerialize(): array|stdClass|MongoDB\BSON\Document|MongoDB\BSON\PackedArray
abstract public function MongoDB\BSON\Unserializable::bsonUnserialize(array `$data`): void
}

# MongoDB\BSON\Persistable::bsonSerialize

(mongodb >=1.0.0)

MongoDB\BSON\Persistable::bsonSerialize — Provides an array or document to serialize as BSON

### 説明

abstract public function 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 2.0.0 | Return types previously declared as tentative are now enforced.
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

## 目次

- MongoDB\BSON\Persistable::bsonSerialize — Provides an array or document to serialize as BSON

# 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 function bsonSerialize(): array|stdClass|MongoDB\BSON\Document|MongoDB\BSON\PackedArray
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | Return types previously declared as tentative are now enforced.
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

(mongodb >=1.0.0)

MongoDB\BSON\Serializable::bsonSerialize — Provides an array or document to serialize as BSON

### 説明

abstract public function 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\Document::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 2.0.0 | Return types previously declared as tentative are now enforced.
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'];
        }
    }

    echo MongoDB\BSON\Document::fromPHP(new MyDocument)->toRelaxedExtendedJSON(), "\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];
        }
    }

    echo MongoDB\BSON\Document::fromPHP(new MyArray)->toRelaxedExtendedJSON(), "\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];

    echo MongoDB\BSON\Document::fromPHP($value)->toRelaxedExtendedJSON(), "\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];

    echo MongoDB\BSON\Document::fromPHP($value)->toRelaxedExtendedJSON(), "\n";

    ?>

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

    { "array" : [ 1, 2, 3 ] }

### 参考

- MongoDB\BSON\Unserializable::bsonUnserialize() - Constructs the object from a BSON array or document
- MongoDB\BSON\Persistable
- Persisting Data

## 目次

- MongoDB\BSON\Serializable::bsonSerialize — Provides an array or document to serialize as BSON

# 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 function bsonUnserialize(array `$data`): void
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | Return types previously declared as tentative are now enforced.
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

(mongodb >=1.0.0)

MongoDB\BSON\Unserializable::bsonUnserialize — Constructs the object from a BSON array or document

### 説明

abstract public function 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.

### 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | Return types previously declared as tentative are now enforced.

### 例

例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\Document::fromJSON('{ "foo": "bar" }');

    var_dump($bson->toPHP(['root' => 'MyDocument']));

    ?>

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

    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

## 目次

- MongoDB\BSON\Unserializable::bsonUnserialize — Constructs the object from a BSON array or document

# 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 function getData(): string
abstract public function getType(): int
abstract public function __toString(): string
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | Return types previously declared as tentative are now enforced.
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

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::getData — Returns the BinaryInterface's data

### 説明

abstract public function MongoDB\BSON\BinaryInterface::getData(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the BinaryInterface's data.

### 参考

- MongoDB\BSON\Binary::getData() - Returns the Binary's data

# MongoDB\BSON\BinaryInterface::getType

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::getType — Returns the BinaryInterface's type

### 説明

abstract public function MongoDB\BSON\BinaryInterface::getType(): int

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the BinaryInterface's type.

### 参考

- MongoDB\BSON\Binary::getType() - Returns the Binary's type

# MongoDB\BSON\BinaryInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\BinaryInterface::__toString — Returns the BinaryInterface's data

### 説明

abstract public function 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

## 目次

- 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

# 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 function __toString(): string
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | Return types previously declared as tentative are now enforced.
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

(mongodb >=1.3.0)

MongoDB\BSON\Decimal128Interface::__toString — Returns the string representation of this Decimal128Interface

### 説明

abstract public function MongoDB\BSON\Decimal128Interface::__toString(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the string representation of this Decimal128Interface.

### 参考

- MongoDB\BSON\Decimal128::__toString() - Returns the string representation of this Decimal128

## 目次

- MongoDB\BSON\Decimal128Interface::__toString — Returns the string representation of this Decimal128Interface

# 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 function getCode(): string
abstract public function getScope(): ?object
abstract public function __toString(): string
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | Return types previously declared as tentative are now enforced.
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

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::getCode — Returns the JavascriptInterface's code

### 説明

abstract public function MongoDB\BSON\JavascriptInterface::getCode(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the JavascriptInterface's code.

### 参考

- MongoDB\BSON\Javascript::getCode() - Returns the Javascript's code

# MongoDB\BSON\JavascriptInterface::getScope

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::getScope — Returns the JavascriptInterface's scope document

### 説明

abstract public function MongoDB\BSON\JavascriptInterface::getScope(): ?object

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the JavascriptInterface's scope document.

### 参考

- MongoDB\BSON\Javascript::getScope() - Returns the Javascript's scope document

# MongoDB\BSON\JavascriptInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\JavascriptInterface::__toString — Returns the JavascriptInterface's code

### 説明

abstract public function 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

## 目次

- 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

# 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 function getTimestamp(): int
abstract public function __toString(): string
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | Return types previously declared as tentative are now enforced.
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

(mongodb >=1.3.0)

MongoDB\BSON\ObjectIdInterface::getTimestamp — Returns the timestamp component of this ObjectIdInterface

### 説明

abstract public function MongoDB\BSON\ObjectIdInterface::getTimestamp(): int

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the timestamp component of this ObjectIdInterface.

### 参考

- MongoDB\BSON\ObjectId::getTimestamp() - Returns the timestamp component of this ObjectId

# MongoDB\BSON\ObjectIdInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\ObjectIdInterface::__toString — Returns the hexidecimal representation of this ObjectIdInterface

### 説明

abstract public function MongoDB\BSON\ObjectIdInterface::__toString(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the hexidecimal representation of this ObjectIdInterface.

### 参考

- 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

# 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 function getFlags(): string
abstract public function getPattern(): string
abstract public function __toString(): string
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | Return types previously declared as tentative are now enforced.
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

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::getFlags — Returns the RegexInterface's flags

### 説明

abstract public function MongoDB\BSON\RegexInterface::getFlags(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the RegexInterface's flags.

### 参考

- MongoDB\BSON\Regex::getFlags() - Returns the Regex's flags

# MongoDB\BSON\RegexInterface::getPattern

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::getPattern — Returns the RegexInterface's pattern

### 説明

abstract public function MongoDB\BSON\RegexInterface::getPattern(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the RegexInterface's pattern.

### 参考

- MongoDB\BSON\Regex::getPattern() - Returns the Regex's pattern

# MongoDB\BSON\RegexInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\RegexInterface::__toString — Returns the string representation of this RegexInterface

### 説明

abstract public function MongoDB\BSON\RegexInterface::__toString(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the string representation of this RegexInterface.

### 参考

- 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

# 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 function getIncrement(): int
abstract public function getTimestamp(): int
abstract public function __toString(): string
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | Return types previously declared as tentative are now enforced.
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

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::getIncrement — Returns the increment component of this TimestampInterface

### 説明

abstract public function 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

# MongoDB\BSON\TimestampInterface::getTimestamp

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::getTimestamp — Returns the timestamp component of this TimestampInterface

### 説明

abstract public function 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

# MongoDB\BSON\TimestampInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\TimestampInterface::__toString — Returns the string representation of this TimestampInterface

### 説明

abstract public function MongoDB\BSON\TimestampInterface::__toString(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the string representation of this TimestampInterface.

### 参考

- 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

# 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 function toDateTime(): DateTime
abstract public function toDateTimeImmutable(): DateTimeImmutable
abstract public function __toString(): string
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | Return types previously declared as tentative are now enforced.
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

(mongodb >=1.3.0)

MongoDB\BSON\UTCDateTimeInterface::toDateTime — Returns the DateTime representation of this UTCDateTimeInterface

### 説明

abstract public function 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

# MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable

(mongodb >=2.0.0)

MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable — Returns the DateTimeImmutable representation of this UTCDateTimeInterface

### 説明

abstract public function MongoDB\BSON\UTCDateTimeInterface::toDateTimeImmutable(): DateTimeImmutable

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the DateTimeImmutable representation of this UTCDateTimeInterface. The returned DateTimeImmutable will use the UTC time zone.

### 参考

- MongoDB\BSON\UTCDateTime::toDateTimeImmutable() - Returns the DateTimeImmutable representation of this UTCDateTime

# MongoDB\BSON\UTCDateTimeInterface::__toString

(mongodb >=1.3.0)

MongoDB\BSON\UTCDateTimeInterface::__toString — Returns the string representation of this UTCDateTimeInterface

### 説明

abstract public function MongoDB\BSON\UTCDateTimeInterface::__toString(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the string representation of this UTCDateTimeInterface.

### 参考

- 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::toDateTimeImmutable — Returns the DateTimeImmutable representation of this UTCDateTimeInterface
- MongoDB\BSON\UTCDateTimeInterface::__toString — Returns the string representation of this UTCDateTimeInterface

# The MongoDB\BSON\DBPointer class

(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, JsonSerializable, Stringable {
/* メソッド */
final private function __construct()
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This class no longer implements the Serializable interface.
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.

# MongoDB\BSON\DBPointer::__construct

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::__construct — Construct a new DBPointer (unused)

### 説明

final private function MongoDB\BSON\DBPointer::__construct()

MongoDB\BSON\DBPointer objects are created through conversion from a deprecated BSON type and cannot be constructed directly.

### パラメータ

この関数にはパラメータはありません。

### 参考

- » BSON Types

# MongoDB\BSON\DBPointer::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::jsonSerialize — Returns a representation that can be converted to JSON

### 説明

final public function 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

# MongoDB\BSON\DBPointer::__toString

(mongodb >=1.4.0)

MongoDB\BSON\DBPointer::__toString — Returns an empty string

### 説明

final public function MongoDB\BSON\DBPointer::__toString(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns an empty string.

### 参考

- » BSON Types

## 目次

- 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::__toString — Returns an empty string

# 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, JsonSerializable, Stringable {
/* メソッド */
final public function __construct(int|string `$value`)
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This class no longer implements the Serializable interface.
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

(mongodb >=1.5.0)

MongoDB\BSON\Int64::__construct — Construct a new Int64

### 説明

final public function 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

# MongoDB\BSON\Int64::jsonSerialize

(mongodb >=1.5.0)

MongoDB\BSON\Int64::jsonSerialize — Returns a representation that can be converted to JSON

### 説明

final public function 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

# MongoDB\BSON\Int64::__toString

(mongodb >=1.5.0)

MongoDB\BSON\Int64::__toString — Returns the string representation of this Int64

### 説明

final public function 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

## 目次

- MongoDB\BSON\Int64::__construct — Construct a new Int64
- MongoDB\BSON\Int64::jsonSerialize — Returns a representation that can be converted to JSON
- MongoDB\BSON\Int64::__toString — Returns the string representation of this Int64

# The MongoDB\BSON\Symbol class

(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, JsonSerializable, Stringable {
/* メソッド */
final private function __construct()
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This class no longer implements the Serializable interface.
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.

# MongoDB\BSON\Symbol::__construct

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::__construct — Construct a new Symbol (unused)

### 説明

final private function MongoDB\BSON\Symbol::__construct()

MongoDB\BSON\Symbol objects are created through conversion from a deprecated BSON type and cannot be constructed directly.

### パラメータ

この関数にはパラメータはありません。

### 参考

- » BSON Types

# MongoDB\BSON\Symbol::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::jsonSerialize — Returns a representation that can be converted to JSON

### 説明

final public function 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

# MongoDB\BSON\Symbol::__toString

(mongodb >=1.4.0)

MongoDB\BSON\Symbol::__toString — Returns the Symbol as a string

### 説明

final public function MongoDB\BSON\Symbol::__toString(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the string representation of this Symbol.

### 参考

- » BSON Types

## 目次

- 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::__toString — Returns the Symbol as a string

# The MongoDB\BSON\Undefined class

(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, JsonSerializable, Stringable {
/* メソッド */
final private function __construct()
final public function jsonSerialize(): mixed
final public function __toString(): string
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This class no longer implements the Serializable interface.
PECL mongodb 1.12.0 | Implements Stringable for PHP 8.0+.

# MongoDB\BSON\Undefined::__construct

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::__construct — Construct a new Undefined (unused)

### 説明

final private function MongoDB\BSON\Undefined::__construct()

MongoDB\BSON\Undefined objects are created through conversion from a deprecated BSON type and cannot be constructed directly.

### パラメータ

この関数にはパラメータはありません。

### 参考

- » BSON Types

# MongoDB\BSON\Undefined::jsonSerialize

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::jsonSerialize — Returns a representation that can be converted to JSON

### 説明

final public function 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

# MongoDB\BSON\Undefined::__toString

(mongodb >=1.4.0)

MongoDB\BSON\Undefined::__toString — Returns an empty string

### 説明

final public function MongoDB\BSON\Undefined::__toString(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns an empty string.

### 参考

- » BSON Types

## 目次

- 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::__toString — Returns an empty string

# Monitoring classes and subscriber functions

## 目次

- 関数
- MongoDB\Driver\Monitoring\CommandFailedEvent
- MongoDB\Driver\Monitoring\CommandStartedEvent
- MongoDB\Driver\Monitoring\CommandSucceededEvent
- MongoDB\Driver\Monitoring\ServerChangedEvent
- MongoDB\Driver\Monitoring\ServerClosedEvent
- MongoDB\Driver\Monitoring\ServerOpeningEvent
- MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent
- MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent
- MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent
- MongoDB\Driver\Monitoring\TopologyChangedEvent
- MongoDB\Driver\Monitoring\TopologyClosedEvent
- MongoDB\Driver\Monitoring\TopologyOpeningEvent
- MongoDB\Driver\Monitoring\CommandSubscriber
- MongoDB\Driver\Monitoring\LogSubscriber
- MongoDB\Driver\Monitoring\SDAMSubscriber
- MongoDB\Driver\Monitoring\Subscriber

# 関数

# MongoDB\Driver\Monitoring\addSubscriber

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\addSubscriber — Registers a monitoring event subscriber globally

### 説明

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

# MongoDB\Driver\Monitoring\removeSubscriber

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\removeSubscriber — Unregisters a monitoring event subscriber globally

### 説明

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

## 目次

- MongoDB\Driver\Monitoring\addSubscriber — Registers a monitoring event subscriber globally
- MongoDB\Driver\Monitoring\removeSubscriber — Unregisters a monitoring event subscriber globally

# 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 {
/* プロパティ */
public readonly string $host;
public readonly int $port;
public readonly string $commandName;
public readonly string $databaseName;
public readonly int $duration;
public readonly Exception $error;
public readonly object $reply;
public readonly string $operationId;
public readonly string $requestId;
public readonly ?MongoDB\BSON\ObjectId $serviceId;
public readonly ?int $serverConnectionId;
/* メソッド */
final public function getCommandName(): string
final public function getDatabaseName(): string
final public function getDurationMicros(): int
final public function getError(): Exception
final public function getHost(): string
final public function getOperationId(): string
final public function getPort(): int
final public function getReply(): object
final public function getRequestId(): string
final public function getServer(): MongoDB\Driver\Server
final public function getServerConnectionId(): ?int
final public function getServiceId(): ?MongoDB\BSON\ObjectId
}

## プロパティ

host
  The hostname of the server that executed the command.
port
  The port of the server that executed the command.
commandName
  The command name.
databaseName
  The database name.
duration
  The duration of the command in microseconds. The duration is a calculated value that includes the time to send the message and receive the response from the server.
error
  The exception that was thrown when the command failed.
reply
  The failure reply document returned by the server.
operationId
  The operation ID. This may be used to link events together such as bulk writes, which may dispatch multiple commands.
requestId
  The request ID. This may be used to associate this MongoDB\Driver\Monitoring\CommandFailedEvent with a corresponding MongoDB\Driver\Monitoring\CommandStartedEvent.
serviceId
  The service ID, or `null` if the server does not support it (i.e. not using load-balanced mode).
serverConnectionId
  The server connection ID, or `null` if not available.

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties. The duration property replaces the getDurationMicros() method.

# MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getCommandName — Returns the command name

### 説明

final public function 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)

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

# MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getDurationMicros — Returns the command's duration in microseconds

### 説明

final public function 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)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getError

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getError — Returns the Exception associated with the failed command

### 説明

final public function 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)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getHost

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getHost — Returns the server hostname for the command

### 説明

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getHost(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the hostname of the server on which the command was executed.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId — Returns the command's operation ID

### 説明

final public function 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)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getPort

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getPort — Returns the server port for the command

### 説明

final public function MongoDB\Driver\Monitoring\CommandFailedEvent::getPort(): int

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the port of the server on which the command was executed.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\CommandFailedEvent::getReply

(mongodb >=1.5.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getReply — Returns the command reply document

### 説明

final public function 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

# MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getRequestId — Returns the command's request ID

### 説明

final public function 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)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getServer

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getServer — Returns the Server on which the command was executed

警告

This method has been DEPRECATED as of extension version 1.20.0 and was removed in 2.0. Applications should use MongoDB\Driver\Monitoring\CommandFailedEvent::getHost() and MongoDB\Driver\Monitoring\CommandFailedEvent::getPort() instead.

### 説明

final public function 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.

### 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This method was removed.

### 参考

- MongoDB\Driver\Monitoring\CommandStartedEvent::getServer() - Returns the Server on which the command was executed
- Application Performance Monitoring (APM)

# MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId

(mongodb >=1.14.0)

MongoDB\Driver\Monitoring\CommandFailedEvent::getServerConnectionId — Returns the server connection ID for the command

### 説明

final public function 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.

# 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 function 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.

## 目次

- 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::getHost — Returns the server hostname for the command
- MongoDB\Driver\Monitoring\CommandFailedEvent::getOperationId — Returns the command's operation ID
- MongoDB\Driver\Monitoring\CommandFailedEvent::getPort — Returns the server port for the command
- 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

# 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 {
/* プロパティ */
public readonly string $host;
public readonly int $port;
public readonly string $commandName;
public readonly string $databaseName;
public readonly object $command;
public readonly string $operationId;
public readonly string $requestId;
public readonly ?MongoDB\BSON\ObjectId $serviceId;
public readonly ?int $serverConnectionId;
/* メソッド */
final public function getCommand(): object
final public function getCommandName(): string
final public function getDatabaseName(): string
final public function getHost(): string
final public function getOperationId(): string
final public function getPort(): int
final public function getRequestId(): string
final public function getServer(): MongoDB\Driver\Server
final public function getServerConnectionId(): ?int
final public function getServiceId(): ?MongoDB\BSON\ObjectId
}

## プロパティ

host
  The hostname of the server that executed the command.
port
  The port of the server that executed the command.
commandName
  The command name.
databaseName
  The database name.
command
  The command document.
operationId
  The operation ID. This may be used to link events together such as bulk writes, which may dispatch multiple commands.
requestId
  The request ID. This may be used to associate this MongoDB\Driver\Monitoring\CommandStartedEvent with a corresponding MongoDB\Driver\Monitoring\CommandSucceededEvent or MongoDB\Driver\Monitoring\CommandFailedEvent.
serviceId
  The service ID, or `null` if the server does not support it (i.e. not using load-balanced mode).
serverConnectionId
  The server connection ID, or `null` if not available.

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getCommand — Returns the command document

### 説明

final public function 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

# MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getCommandName — Returns the command name

### 説明

final public function 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)

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

# MongoDB\Driver\Monitoring\CommandStartedEvent::getHost

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getHost — Returns the server hostname for the command

### 説明

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getHost(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the hostname of the server on which the command was executed.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId — Returns the command's operation ID

### 説明

final public function 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)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getPort

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getPort — Returns the server port for the command

### 説明

final public function MongoDB\Driver\Monitoring\CommandStartedEvent::getPort(): int

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the port of the server on which the command was executed.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getRequestId — Returns the command's request ID

### 説明

final public function 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)

# MongoDB\Driver\Monitoring\CommandStartedEvent::getServer

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getServer — Returns the Server on which the command was executed

警告

This method has been DEPRECATED as of extension version 1.20.0 and was removed in 2.0. Applications should use MongoDB\Driver\Monitoring\CommandStartedEvent::getHost() and MongoDB\Driver\Monitoring\CommandStartedEvent::getPort() instead.

### 説明

final public function 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.

### 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This method was removed.

### 参考

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

# MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId

(mongodb >=1.14.0)

MongoDB\Driver\Monitoring\CommandStartedEvent::getServerConnectionId — Returns the server connection ID for the command

### 説明

final public function 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.

# 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 function 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.

## 目次

- 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::getHost — Returns the server hostname for the command
- MongoDB\Driver\Monitoring\CommandStartedEvent::getOperationId — Returns the command's operation ID
- MongoDB\Driver\Monitoring\CommandStartedEvent::getPort — Returns the server port for the command
- 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

# 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 {
/* プロパティ */
public readonly string $host;
public readonly int $port;
public readonly string $commandName;
public readonly string $databaseName;
public readonly int $duration;
public readonly object $reply;
public readonly string $operationId;
public readonly string $requestId;
public readonly ?MongoDB\BSON\ObjectId $serviceId;
public readonly ?int $serverConnectionId;
/* メソッド */
final public function getCommandName(): string
final public function getDatabaseName(): string
final public function getDurationMicros(): int
final public function getHost(): string
final public function getOperationId(): string
final public function getPort(): int
final public function getReply(): object
final public function getRequestId(): string
final public function getServer(): MongoDB\Driver\Server
final public function getServerConnectionId(): ?int
final public function getServiceId(): ?MongoDB\BSON\ObjectId
}

## プロパティ

host
  The hostname of the server that executed the command.
port
  The port of the server that executed the command.
commandName
  The command name.
databaseName
  The database name.
duration
  The duration of the command in microseconds. The duration is a calculated value that includes the time to send the message and receive the response from the server.
reply
  The reply document returned by the server.
operationId
  The operation ID. This may be used to link events together such as bulk writes, which may dispatch multiple commands.
requestId
  The request ID. This may be used to associate this MongoDB\Driver\Monitoring\CommandSucceededEvent with a corresponding MongoDB\Driver\Monitoring\CommandStartedEvent.
serviceId
  The service ID, or `null` if the server does not support it (i.e. not using load-balanced mode).
serverConnectionId
  The server connection ID, or `null` if not available.

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties. The duration property replaces the getDurationMicros() method.

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getCommandName — Returns the command name

### 説明

final public function 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)

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

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getDurationMicros — Returns the command's duration in microseconds

### 説明

final public function 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)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost — Returns the server hostname for the command

### 説明

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the hostname of the server on which the command was executed.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId — Returns the command's operation ID

### 説明

final public function 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)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort

(mongodb >=1.20.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort — Returns the server port for the command

### 説明

final public function MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort(): int

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the port of the server on which the command was executed.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getReply — Returns the command reply document

### 説明

final public function 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

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getRequestId — Returns the command's request ID

### 説明

final public function 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)

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServer — Returns the Server on which the command was executed

警告

This method has been DEPRECATED as of extension version 1.20.0 and was removed in 2.0. Applications should use MongoDB\Driver\Monitoring\CommandSucceededEvent::getHost() and MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort() instead.

### 説明

final public function 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.

### 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This method was removed.

### 参考

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

# MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId

(mongodb >=1.14.0)

MongoDB\Driver\Monitoring\CommandSucceededEvent::getServerConnectionId — Returns the server connection ID for the command

### 説明

final public function 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.

# 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 function 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.

## 目次

- 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::getHost — Returns the server hostname for the command
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getOperationId — Returns the command's operation ID
- MongoDB\Driver\Monitoring\CommandSucceededEvent::getPort — Returns the server port for the command
- 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

# The MongoDB\Driver\Monitoring\ServerChangedEvent class

(mongodb >=1.13.0)

## はじめに

The MongoDB\Driver\Monitoring\ServerChangedEvent class encapsulates information about a changed server description. For example, a server's type changing from secondary to primary would cause its server description to change.

## クラス概要

final class MongoDB\Driver\Monitoring\ServerChangedEvent {
/* プロパティ */
public readonly string $host;
public readonly int $port;
public readonly MongoDB\BSON\ObjectId $topologyId;
public readonly MongoDB\Driver\ServerDescription $newDescription;
public readonly MongoDB\Driver\ServerDescription $previousDescription;
/* メソッド */
final public function getHost(): string
final public function getNewDescription(): MongoDB\Driver\ServerDescription
final public function getPort(): int
final public function getPreviousDescription(): MongoDB\Driver\ServerDescription
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## プロパティ

host
  The hostname of the server.
port
  The port of the server.
topologyId
  The topology ID.
newDescription
  The new server description.
previousDescription
  The previous server description.

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getHost — Returns the hostname of the server

### 説明

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getHost(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the hostname of the server.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getNewDescription — Returns the new description for the server

### 説明

final public function 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.

# 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 function MongoDB\Driver\Monitoring\ServerChangedEvent::getPort(): int

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the port on which this server is listening.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getPreviousDescription — Returns the previous description for the server

### 説明

final public function 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.

# MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId — Returns the topology ID associated with this server

### 説明

final public function MongoDB\Driver\Monitoring\ServerChangedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the topology ID.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

## 目次

- 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

# The MongoDB\Driver\Monitoring\ServerClosedEvent class

(mongodb >=1.13.0)

## はじめに

The MongoDB\Driver\Monitoring\ServerClosedEvent class encapsulates information about a closed server. This corresponds to an existing server being removed from the topology.

## クラス概要

final class MongoDB\Driver\Monitoring\ServerClosedEvent {
/* プロパティ */
public readonly string $host;
public readonly int $port;
public readonly MongoDB\BSON\ObjectId $topologyId;
/* メソッド */
final public function getHost(): string
final public function getPort(): int
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## プロパティ

host
  The hostname of the server.
port
  The port of the server.
topologyId
  The topology ID.

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.

# MongoDB\Driver\Monitoring\ServerClosedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerClosedEvent::getHost — Returns the hostname of the server

### 説明

final public function MongoDB\Driver\Monitoring\ServerClosedEvent::getHost(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the hostname of the server.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# 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 function MongoDB\Driver\Monitoring\ServerClosedEvent::getPort(): int

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the port on which this server is listening.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId — Returns the topology ID associated with this server

### 説明

final public function MongoDB\Driver\Monitoring\ServerClosedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the topology ID.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

## 目次

- 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

# The MongoDB\Driver\Monitoring\ServerOpeningEvent class

(mongodb >=1.13.0)

## はじめに

The MongoDB\Driver\Monitoring\ServerOpeningEvent class encapsulates information about an opened server. This corresponds to a new server being added to the topology.

## クラス概要

final class MongoDB\Driver\Monitoring\ServerOpeningEvent {
/* プロパティ */
public readonly string $host;
public readonly int $port;
public readonly MongoDB\BSON\ObjectId $topologyId;
/* メソッド */
final public function getHost(): string
final public function getPort(): int
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## プロパティ

host
  The hostname of the server.
port
  The port of the server.
topologyId
  The topology ID.

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.

# MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost — Returns the hostname of the server

### 説明

final public function MongoDB\Driver\Monitoring\ServerOpeningEvent::getHost(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the hostname of the server.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# 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 function MongoDB\Driver\Monitoring\ServerOpeningEvent::getPort(): int

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the port on which this server is listening.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId — Returns the topology ID associated with this server

### 説明

final public function MongoDB\Driver\Monitoring\ServerOpeningEvent::getTopologyId(): MongoDB\BSON\ObjectId

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the topology ID.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

## 目次

- 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

# The MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent class

(mongodb >=1.13.0)

## はじめに

The MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent class encapsulates information about a failed server heartbeat (i.e. » hello command issued through » server monitoring).

## クラス概要

final class MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent {
/* プロパティ */
public readonly string $host;
public readonly int $port;
public readonly bool $awaited;
public readonly int $duration;
public readonly Exception $error;
/* メソッド */
final public function getDurationMicros(): int
final public function getError(): Exception
final public function getHost(): string
final public function getPort(): int
final public function isAwaited(): bool
}

## プロパティ

host
  The hostname of the server.
port
  The port of the server.
awaited
  Whether the heartbeat used a streaming protocol. The extension does not use the streaming protocol for monitoring, so this method will always return `false`.
duration
  The duration of the heartbeat in microseconds. The duration is a calculated value that includes the time to send the message and receive the response from the server.
error
  The exception that was thrown when the heartbeat failed.

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties. The duration property replaces the getDurationMicros() method.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getDurationMicros — Returns the heartbeat's duration in microseconds

### 説明

final public function 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.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError — Returns the Exception associated with the failed heartbeat

### 説明

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getError(): Exception

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the Exception associated with the failed heartbeat.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost — Returns the hostname of the server

### 説明

final public function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getHost(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the hostname of the server.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# 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 function MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::getPort(): int

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the port on which this server is listening.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent::isAwaited — Returns whether the heartbeat used a streaming protocol

### 説明

final public function 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.

## 目次

- 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

# The MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent class

(mongodb >=1.13.0)

## はじめに

The MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent class encapsulates information about a started server heartbeat (i.e. » hello command issued through » server monitoring).

## クラス概要

final class MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent {
/* プロパティ */
public readonly string $host;
public readonly int $port;
public readonly bool $awaited;
/* メソッド */
final public function getHost(): string
final public function getPort(): int
final public function isAwaited(): bool
}

## プロパティ

host
  The hostname of the server.
port
  The port of the server.
awaited
  Whether the heartbeat used a streaming protocol. The extension does not use the streaming protocol for monitoring, so this method will always return `false`.

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.

# MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost — Returns the hostname of the server

### 説明

final public function MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getHost(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the hostname of the server.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# 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 function MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::getPort(): int

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the port on which this server is listening.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent::isAwaited — Returns whether the heartbeat used a streaming protocol

### 説明

final public function 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.

## 目次

- 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

# The MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent class

(mongodb >=1.13.0)

## はじめに

The MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent class encapsulates information about a successful server heartbeat (i.e. » hello command issued through » server monitoring).

## クラス概要

final class MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent {
/* プロパティ */
public readonly string $host;
public readonly int $port;
public readonly bool $awaited;
public readonly int $duration;
public readonly object $reply;
/* メソッド */
final public function getDurationMicros(): int
final public function getHost(): string
final public function getPort(): int
final public function getReply(): object
final public function isAwaited(): bool
}

## プロパティ

host
  The hostname of the server.
port
  The port of the server.
awaited
  Whether the heartbeat used a streaming protocol. The extension does not use the streaming protocol for monitoring, so this method will always return `false`.
duration
  The duration of the heartbeat in microseconds. The duration is a calculated value that includes the time to send the message and receive the response from the server.
reply
  The reply document returned by the server.

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties. The duration property replaces the getDurationMicros() method.

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getDurationMicros — Returns the heartbeat's duration in microseconds

### 説明

final public function 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.

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost — Returns the hostname of the server

### 説明

final public function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getHost(): string

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the hostname of the server.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# 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 function MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getPort(): int

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the port on which this server is listening.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::getReply — Returns the heartbeat reply document

### 説明

final public function 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

# MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent::isAwaited — Returns whether the heartbeat used a streaming protocol

### 説明

final public function 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.

## 目次

- 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

# The MongoDB\Driver\Monitoring\TopologyChangedEvent class

(mongodb >=1.13.0)

## はじめに

The MongoDB\Driver\Monitoring\TopologyChangedEvent class encapsulates information about a changed topology description. For example, a topology discovering a new replica set primary would cause its topology description to change.

## クラス概要

final class MongoDB\Driver\Monitoring\TopologyChangedEvent {
/* プロパティ */
public readonly MongoDB\BSON\ObjectId $topologyId;
public readonly MongoDB\Driver\TopologyDescription $newDescription;
public readonly MongoDB\Driver\TopologyDescription $previousDescription;
/* メソッド */
final public function getNewDescription(): MongoDB\Driver\TopologyDescription
final public function getPreviousDescription(): MongoDB\Driver\TopologyDescription
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## プロパティ

topologyId
  The topology ID.
newDescription
  The new topology description.
previousDescription
  The previous topology description.

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.

# MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyChangedEvent::getNewDescription — Returns the new description for the topology

### 説明

final public function 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.

# MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyChangedEvent::getPreviousDescription — Returns the previous description for the topology

### 説明

final public function 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.

# MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId — Returns the topology ID

### 説明

final public function MongoDB\Driver\Monitoring\TopologyChangedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the topology ID.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

## 目次

- 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

# The MongoDB\Driver\Monitoring\TopologyClosedEvent class

(mongodb >=1.13.0)

## はじめに

The MongoDB\Driver\Monitoring\TopologyClosedEvent class encapsulates information about a closed topology.

> 注意: Due to the driver's connection handling and persistence behavior, this event can only be observed when a MongoDB\Driver\Manager is created with the `"disableClientPersistence"` driver option and freed before request shutdown (RSHUTDOWN).

## クラス概要

final class MongoDB\Driver\Monitoring\TopologyClosedEvent {
/* プロパティ */
public readonly MongoDB\BSON\ObjectId $topologyId;
/* メソッド */
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## プロパティ

topologyId
  The topology ID.

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.

# MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId — Returns the topology ID

### 説明

final public function MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId(): MongoDB\BSON\ObjectId

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the topology ID.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

## 目次

- MongoDB\Driver\Monitoring\TopologyClosedEvent::getTopologyId — Returns the topology ID

# The MongoDB\Driver\Monitoring\TopologyOpeningEvent class

(mongodb >=1.13.0)

## はじめに

The MongoDB\Driver\Monitoring\TopologyOpeningEvent class encapsulates information about an opened topology.

> 注意: Due to the driver's connection handling and persistence behavior, this event may not be observed if a MongoDB\Driver\Manager uses a previously persisted » libmongoc client.

## クラス概要

final class MongoDB\Driver\Monitoring\TopologyOpeningEvent {
/* プロパティ */
public readonly MongoDB\BSON\ObjectId $topologyId;
/* メソッド */
final public function getTopologyId(): MongoDB\BSON\ObjectId
}

## プロパティ

topologyId
  The topology ID.

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.3.0 | Added public readonly properties.

# MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId — Returns the topology ID

### 説明

final public function MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId(): MongoDB\BSON\ObjectId

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the topology ID.

### エラー / 例外

- Throws MongoDB\Driver\Exception\InvalidArgumentException on argument parsing errors.

## 目次

- MongoDB\Driver\Monitoring\TopologyOpeningEvent::getTopologyId — Returns the topology ID

# 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 function commandFailed(MongoDB\Driver\Monitoring\CommandFailedEvent `$event`): void
abstract public function commandStarted(MongoDB\Driver\Monitoring\CommandStartedEvent `$event`): void
abstract public function commandSucceeded(MongoDB\Driver\Monitoring\CommandSucceededEvent `$event`): void
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | Return types previously declared as tentative are now enforced.
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

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandFailed — Notification method for a failed command

### 説明

abstract public function 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)

# MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandStarted — Notification method for a started command

### 説明

abstract public function 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)

# MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded

(mongodb >=1.3.0)

MongoDB\Driver\Monitoring\CommandSubscriber::commandSucceeded — Notification method for a successful command

### 説明

abstract public function 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)

## 目次

- 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

# 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 function 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

(mongodb >=1.17.0)

MongoDB\Driver\Monitoring\LogSubscriber::log — Notification method for a log message

### 説明

abstract public function 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

## 目次

- MongoDB\Driver\Monitoring\LogSubscriber::log — Notification method for a log message

# 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 function serverChanged(MongoDB\Driver\Monitoring\ServerChangedEvent `$event`): void
abstract public function serverClosed(MongoDB\Driver\Monitoring\ServerClosedEvent `$event`): void
abstract public function serverHeartbeatFailed(MongoDB\Driver\Monitoring\ServerHeartbeatFailedEvent `$event`): void
abstract public function serverHeartbeatStarted(MongoDB\Driver\Monitoring\ServerHeartbeatStartedEvent `$event`): void
abstract public function serverHeartbeatSucceeded(MongoDB\Driver\Monitoring\ServerHeartbeatSucceededEvent `$event`): void
abstract public function serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent `$event`): void
abstract public function topologyChanged(MongoDB\Driver\Monitoring\TopologyChangedEvent `$event`): void
abstract public function topologyClosed(MongoDB\Driver\Monitoring\TopologyClosedEvent `$event`): void
abstract public function topologyOpening(MongoDB\Driver\Monitoring\TopologyOpeningEvent `$event`): void
}

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | Return types previously declared as tentative are now enforced.
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

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverChanged — Notification method for a server description change

### 説明

abstract public function 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. For example, a server's type changing from secondary to primary would cause its server description to change.

### パラメータ

`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

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed — Notification method for closing a server

### 説明

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverClosed(MongoDB\Driver\Monitoring\ServerClosedEvent `$event`): void

If the subscriber is registered, this method is called when an existing server is removed from the topology.

### パラメータ

`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

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatFailed — Notification method for a failed server heartbeat

### 説明

abstract public function 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

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatStarted — Notification method for a started server heartbeat

### 説明

abstract public function 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

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverHeartbeatSucceeded — Notification method for a successful server heartbeat

### 説明

abstract public function 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

# MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening — Notification method for opening a server

### 説明

abstract public function MongoDB\Driver\Monitoring\SDAMSubscriber::serverOpening(MongoDB\Driver\Monitoring\ServerOpeningEvent `$event`): void

If the subscriber is registered, this method is called when a new server is added to the topology.

### パラメータ

`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

# MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::topologyChanged — Notification method for a topology description change

### 説明

abstract public function 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. For example, a topology discovering a new replica set primary would cause its topology description to change.

### パラメータ

`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

# MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::topologyClosed — Notification method for closing the topology

### 説明

abstract public function 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.

> 注意: Due to the driver's connection handling and persistence behavior, this event can only be observed when a MongoDB\Driver\Manager is created with the `"disableClientPersistence"` driver option and freed before request shutdown (RSHUTDOWN).

### パラメータ

`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

# MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening

(mongodb >=1.13.0)

MongoDB\Driver\Monitoring\SDAMSubscriber::topologyOpening — Notification method for opening the topology

### 説明

abstract public function 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.

> 注意: Due to the driver's connection handling and persistence behavior, this event may not be observed if a MongoDB\Driver\Manager uses a previously persisted » libmongoc client.

### パラメータ

`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

## 目次

- 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

# 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
- MongoDB\Driver\Exception\BulkWriteException
- MongoDB\Driver\Exception\BulkWriteCommandException
- MongoDB\Driver\Exception\CommandException
- MongoDB\Driver\Exception\ConnectionException
- MongoDB\Driver\Exception\ConnectionTimeoutException
- MongoDB\Driver\Exception\EncryptionException
- MongoDB\Driver\Exception\Exception
- MongoDB\Driver\Exception\ExecutionTimeoutException
- MongoDB\Driver\Exception\InvalidArgumentException
- MongoDB\Driver\Exception\LogicException
- MongoDB\Driver\Exception\RuntimeException
- MongoDB\Driver\Exception\ServerException
- MongoDB\Driver\Exception\SSLConnectionException
- MongoDB\Driver\Exception\UnexpectedValueException
- MongoDB\Driver\Exception\WriteException
- 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 function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function 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\ServerException implements MongoDB\Driver\Exception\Exception {
/* プロパティ */
public readonly 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 function getWriteResult(): MongoDB\Driver\WriteResult
/* 継承したメソッド */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## プロパティ

writeResult
  The MongoDB\Driver\WriteResult associated with the failed write operation.

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.3.0 | The writeResult property is now public readonly.
PECL mongodb 2.0.0 | This class now extends MongoDB\Driver\Exception\ServerException instead of MongoDB\Driver\Exception\WriteException.

# MongoDB\Driver\Exception\BulkWriteException::getWriteResult

(mongodb >= 1.0.0)

MongoDB\Driver\Exception\BulkWriteException::getWriteResult — Returns the WriteResult for the failed write operation

### 説明

final public function MongoDB\Driver\Exception\BulkWriteException::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\BulkWriteException::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\BulkWriteException $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\Driver\Exception\BulkWriteException::getWriteResult — Returns the WriteResult for the failed write operation

# The MongoDB\Driver\Exception\BulkWriteCommandException class

(mongodb >=2.1.0)

## はじめに

Exception thrown due to failed execution of a MongoDB\Driver\BulkWriteCommand. The methods of this class provide more details of the error that occurred, including the error reply and partial results from the bulk write.

## クラス概要

class MongoDB\Driver\Exception\BulkWriteCommandException extends MongoDB\Driver\Exception\ServerException implements MongoDB\Driver\Exception\Exception {
/* プロパティ */
private ?MongoDB\BSON\Document $errorReply;
private ?MongoDB\Driver\BulkWriteCommandResult $partialResult;
private array $writeConcernErrors;
private array $writeErrors;
/* 継承したプロパティ */
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 function getErrorReply(): ?MongoDB\BSON\Document
final public function getPartialResult(): ?MongoDB\Driver\BulkWriteCommandResult
final public function getWriteConcernErrors(): array
final public function getWriteErrors(): array
/* 継承したメソッド */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## プロパティ

errorReply
  Any top-level error that occurred when attempting to communicate with the server or execute the bulk write. This value may be `null` if the exception was thrown due to errors occurring on individual writes.
partialResult
  A MongoDB\Driver\BulkWriteCommandResult reporting the result of any successful operations that were performed before the error was encountered. This value may be `null` if it cannot be determined that at least one write was successfully performed (and acknowledged).
writeConcernErrors
  An array of any MongoDB\Driver\WriteConcernErrors that occurred while executing the bulk write. This list may have multiple items if more than one server command was required to execute the bulk write.
writeErrors
  An array of any MongoDB\Driver\WriteErrors that occurred during the execution of individual write operations. Array keys will correspond to the index of the write operation from MongoDB\Driver\BulkWriteCommand. This map will contain at most one entry if the bulk write was ordered.

# MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply

(mongodb >=2.1.0)

MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply — Returns any top-level command error

### 説明

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply(): ?MongoDB\BSON\Document

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns any top-level error that occurred when attempting to communicate with the server or execute the bulk write. This value may be `null` if the exception was thrown due to errors occurring on individual writes.

### 例

例1 MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    // This example uses configureFailPoint to simulate a top-level command error
    $manager->executeCommand('admin', new MongoDB\Driver\Command([
        'configureFailPoint' => 'failCommand',
        'mode' => ['times' => 1],
        'data' => [
            'failCommands' => ['bulkWrite'],
            'errorCode' => 8, /* UnknownError */
        ],
    ]));

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        var_dump($e->getErrorReply()?->toPHP());
    }

    ?>

上の例の出力は、 たとえば以下のようになります。

    object(stdClass)#12 (6) {
      ["ok"]=>
      float(0)
      ["errmsg"]=>
      string(43) "Failing command via 'failCommand' failpoint"
      ["code"]=>
      int(8)
      ["codeName"]=>
      string(12) "UnknownError"
      ["$clusterTime"]=>
      object(stdClass)#10 (2) {
        ["clusterTime"]=>
        object(MongoDB\BSON\Timestamp)#6 (2) {
          ["increment"]=>
          string(1) "7"
          ["timestamp"]=>
          string(10) "1744319389"
        }
        ["signature"]=>
        object(stdClass)#9 (2) {
          ["hash"]=>
          object(MongoDB\BSON\Binary)#7 (2) {
            ["data"]=>
            string(20) ""
            ["type"]=>
            int(0)
          }
          ["keyId"]=>
          object(MongoDB\BSON\Int64)#8 (1) {
            ["integer"]=>
            string(1) "0"
          }
        }
      }
      ["operationTime"]=>
      object(MongoDB\BSON\Timestamp)#11 (2) {
        ["increment"]=>
        string(1) "7"
        ["timestamp"]=>
        string(10) "1744319389"
      }
    }

### 参考

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command

# MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult

(mongodb >=2.1.0)

MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult — Returns the result of any successful write operations

### 説明

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult(): ?MongoDB\Driver\BulkWriteCommandResult

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns a MongoDB\Driver\BulkWriteCommandResult reporting the result of any successful operations that were performed before the error was encountered. The return value will be `null` if it cannot be determined that at least one write was successfully performed (and acknowledged).

### 例

例1 Partial result if at least one write is successful

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 1]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        $result = $e->getPartialResult();
    }

    var_dump($result?->getInsertedCount());

    ?>

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

    int(1)

例2 No partial result if no writes are successful

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $manager->executeBulkWriteCommand($bulk);

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['_id' => 1]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        $result = $e->getPartialResult();
    }

    var_dump($result?->getInsertedCount());

    ?>

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

    NULL

### 参考

- MongoDB\Driver\BulkWriteCommandResult
- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command

# MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors

(mongodb >=2.1.0)

MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors — Returns any write concern errors

### 説明

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors(): array

### パラメータ

この関数にはパラメータはありません。

### 戻り値

An array of any MongoDB\Driver\WriteConcernErrors that occurred while executing the bulk write. This list may have multiple items if more than one server command was required to execute the bulk write.

### 例

例1 MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand;
    $bulk->insertOne('db.coll', ['x' => 1]);

    $writeConcern = new MongoDB\Driver\WriteConcern(50);

    try {
        $result = $manager->executeBulkWriteCommand($bulk, ['writeConcern' => $writeConcern]);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        var_dump($e->getWriteConcernErrors());
    }

    ?>

上の例の出力は、 たとえば以下のようになります。

    array(1) {
      [0]=>
      object(MongoDB\Driver\WriteConcernError)#6 (3) {
        ["message"]=>
        string(29) "Not enough data-bearing nodes"
        ["code"]=>
        int(100)
        ["info"]=>
        object(stdClass)#8 (1) {
          ["writeConcern"]=>
          object(stdClass)#7 (3) {
            ["w"]=>
            int(50)
            ["wtimeout"]=>
            int(0)
            ["provenance"]=>
            string(14) "clientSupplied"
          }
        }
      }
    }

### 参考

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command
- MongoDB\Driver\WriteConcern
- MongoDB\Driver\WriteConcernError

# MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors

(mongodb >=2.1.0)

MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors — Returns any write errors

### 説明

final public function MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors(): array

### パラメータ

この関数にはパラメータはありません。

### 戻り値

An array of any MongoDB\Driver\WriteErrors that occurred during the execution of individual write operations. Array keys will correspond to the index of the write operation from MongoDB\Driver\BulkWriteCommand. This map will contain at most one entry if the bulk write was ordered.

### 例

例1 MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors() example

    <?php

    $manager = new MongoDB\Driver\Manager;

    $bulk = new MongoDB\Driver\BulkWriteCommand(['ordered' => false]);
    $bulk->deleteMany('db.coll', []);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 1]);
    $bulk->insertOne('db.coll', ['_id' => 1]);

    try {
        $result = $manager->executeBulkWriteCommand($bulk);
    } catch (MongoDB\Driver\Exception\BulkWriteCommandException $e) {
        var_dump($e->getWriteErrors());
    }

    ?>

上の例の出力は、 たとえば以下のようになります。

    array(2) {
      [2]=>
      object(MongoDB\Driver\WriteError)#5 (4) {
        ["message"]=>
        string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(2)
        ["info"]=>
        object(stdClass)#6 (0) {
        }
      }
      [3]=>
      object(MongoDB\Driver\WriteError)#7 (4) {
        ["message"]=>
        string(78) "E11000 duplicate key error collection: db.coll index: _id_ dup key: { _id: 1 }"
        ["code"]=>
        int(11000)
        ["index"]=>
        int(3)
        ["info"]=>
        object(stdClass)#8 (0) {
        }
      }
    }

### 参考

- MongoDB\Driver\Manager::executeBulkWriteCommand() - Execute write operations using the bulkWrite command
- MongoDB\Driver\WriteError

## 目次

- MongoDB\Driver\Exception\BulkWriteCommandException::getErrorReply — Returns any top-level command error
- MongoDB\Driver\Exception\BulkWriteCommandException::getPartialResult — Returns the result of any successful write operations
- MongoDB\Driver\Exception\BulkWriteCommandException::getWriteConcernErrors — Returns any write concern errors
- MongoDB\Driver\Exception\BulkWriteCommandException::getWriteErrors — Returns any write errors

# 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 {
/* プロパティ */
public readonly 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 function getResultDocument(): object
/* 継承したメソッド */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## プロパティ

resultDocument
  The result document associated with the failed command.

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.3.0 | The resultDocument property is now public readonly.

# MongoDB\Driver\Exception\CommandException::getResultDocument

(mongodb >= 1.5.0)

MongoDB\Driver\Exception\CommandException::getResultDocument — Returns the result document for the failed command

### 説明

final public function 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

## 目次

- MongoDB\Driver\Exception\CommandException::getResultDocument — Returns the result document for the failed 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 function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function 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 function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function 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 function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function 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 function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function 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 function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function 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 function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function 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 function hasErrorLabel(string `$errorLabel`): bool
/* 継承したメソッド */
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function 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

(mongodb >= 1.6.0)

MongoDB\Driver\Exception\RuntimeException::hasErrorLabel — Returns whether an error label is associated with an exception

### 説明

final public function 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

## 目次

- MongoDB\Driver\Exception\RuntimeException::hasErrorLabel — Returns whether an error label is associated with an exception

# 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 function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# The MongoDB\Driver\Exception\SSLConnectionException class

(mongodb >= 1.0.0)

警告

This exception class is DEPRECATED as of extension version 1.5.0 and was removed in 2.0. This exception was never thrown by the extension. Applications should use MongoDB\Driver\Exception\ConnectionException instead.

## はじめに

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 function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function 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 function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# The MongoDB\Driver\Exception\WriteException class

(mongodb >= 1.0.0)

警告

This exception class is DEPRECATED as of extension version 1.20.0 and was removed in 2.0. This exception was never directly thrown by the extension. Applications should use MongoDB\Driver\Exception\BulkWriteException instead.

## はじめに

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 function getWriteResult(): MongoDB\Driver\WriteResult
/* 継承したメソッド */
final public function MongoDB\Driver\Exception\RuntimeException::hasErrorLabel(string `$errorLabel`): bool
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## プロパティ

writeResult
  The MongoDB\Driver\WriteResult associated with the failed write operation.

## 変更履歴

バージョン | 説明
--- | ---
PECL mongodb 2.0.0 | This class was removed.
PECL mongodb 1.20.0 | This class has been deprecated and will be removed in version 2.0.
PECL mongodb 1.5.0 | This class now extends MongoDB\Driver\Exception\ServerException instead of MongoDB\Driver\Exception\RuntimeException.

# MongoDB\Driver\Exception\WriteException::getWriteResult

(mongodb >= 1.0.0)

MongoDB\Driver\Exception\WriteException::getWriteResult — Returns the WriteResult for the failed write operation

### 説明

final public function 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\Driver\Exception\WriteException::getWriteResult — Returns the WriteResult for the failed write operation

# 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\BulkWriteCommandException
    - MongoDB\Driver\Exception\CommandException
    - MongoDB\Driver\Exception\ExecutionTimeoutException
    - MongoDB\Driver\Exception\WriteException (deprecated)
      - MongoDB\Driver\Exception\BulkWriteException

- インストール/設定
  - 要件
  - インストール手順
  - 実行時設定
- 定義済み定数
- 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\BulkWriteCommand — The MongoDB\Driver\BulkWriteCommand 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\Driver\BulkWriteCommandResult — The MongoDB\Driver\BulkWriteCommandResult 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\VectorType — The MongoDB\BSON\VectorType enum
  - 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
  - MongoDB\BSON\Int64 — The MongoDB\BSON\Int64 class
  - MongoDB\BSON\Symbol — The MongoDB\BSON\Symbol class
  - MongoDB\BSON\Undefined — The MongoDB\BSON\Undefined class
- 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\BulkWriteCommandException — The MongoDB\Driver\Exception\BulkWriteCommandException 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
  - 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

# MySQL ドライバおよびプラグイン

PHP で MySQL を扱うためのドライバやプラグインには、いくつかの種類があります。

それらの違いや MySQL 用拡張モジュールの機能について、ここで簡単に説明します。

ここで説明している拡張モジュールは、MySQL プロトコルをサポートしています。 それと互換性のあるデータベースサーバーは、 » MariaDB Server, » MySQL Server, » Percona Server for MySQL, » TiDB です。

# MySQL 用 PHP ドライバの概要

# はじめに

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

- 用語説明
- どの API を使うか
- どのライブラリを選ぶか
- コンセプト
  - バッファクエリと非バッファクエリ
  - 文字セット

# MySQL 改良版拡張モジュール

# はじめに

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

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定

## 要件

これらの関数を有効にするには、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` bool

  PHP 側から、LOAD DATA 文によるローカルファイルへのアクセスを許可する。

`mysqli.local_infile_directory` string

  LOCAL DATA 文によるファイルのロードを、 ここで指定したディレクトリに制限する機能を有効にします。

`mysqli.allow_persistent` bool

  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)
  サーバーに対して、クライアントが期限切れパスワードのサンドボックスモードを処理できることを示します。 mysqli_options() と共に使用できます。
`MYSQLI_OPT_LOAD_DATA_LOCAL_DIR` (int)
  有効にすると、このオプションは `LOAD DATA LOCAL` ステートメントで クライアント側の `LOCAL` データのロードを許可するディレクトリを指定します。
`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)

`MYSQLI_INIT_COMMAND` (int)

  MySQL サーバーへの接続時に実行するコマンド。 再接続時にも自動的に再実行されます。

`MYSQLI_CLIENT_CAN_HANDLE_EXPIRED_PASSWORDS` (int)
  サーバーに対して、クライアントが期限切れパスワードのサンドボックスモードを処理できることを示します。 mysqli_real_connect() と共に使用できます。
`MYSQLI_CLIENT_FOUND_ROWS` (int)
  影響を受けた行数ではなく、一致した行数を返します。
`MYSQLI_CLIENT_SSL_VERIFY_SERVER_CERT` (int)
  サーバー証明書を検証します。
`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)
  PHP 8.1 以降、この定数はもはや意味をなしません。 PHP 8.1 より前は、 `mysqlnd` の内部バッファに格納されたフェッチ結果を PHP 変数へコピーするために使用されていました。 デフォルトでは `mysqlnd` は、メモリ内の結果を 重複させないようにコピーではなく参照ロジックを使用します。 しかし、特定の結果セット、たとえば多数の小さな行を持つ結果セットでは、 PHP 変数を個別で早期に解放できるコピー方式の方が 全体的なメモリ使用量を削減る可能性があります。 `mysqlnd` のみで利用可能です。 PHP 8.4.0 で非推奨となりました。
`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)
  カラムの定義に `DEFAULT` 句がありません。これは `NULL` や `AUTO_INCREMENT` カラムには適用されません。なぜならそのようなカラムはそれぞれ デフォルト値として `NULL` および暗黙のデフォルト値を持っているためです。
`MYSQLI_TYPE_DECIMAL` (int)

  フィールドは `DECIMAL` と定義されています。

`MYSQLI_TYPE_NEWDECIMAL` (int)

  精密な `DECIMAL` あるいは `NUMERIC` のフィールドです

`MYSQLI_TYPE_BIT` (int)

  フィールドは `BIT` と定義されています

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

  `MYSQLI_TYPE_ENUM` のエイリアスです。 PHP 8.4.0 で削除されました。

`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_TYPE_VECTOR` (int)

  フィールドは `VECTOR` と定義されています。

`MYSQLI_NEED_DATA`

  バインド変数に、さらにデータを使用可能です。

`MYSQLI_ENUM_FLAG` (int)

  フィールドが `ENUM` として定義されています。

`MYSQLI_BINARY_FLAG` (int)

  フィールドが `BINARY` として定義されています。

`MYSQLI_CURSOR_TYPE_FOR_UPDATE` (int)

  PHP 8.4.0 で削除されました。

`MYSQLI_CURSOR_TYPE_NO_CURSOR` (int)

`MYSQLI_CURSOR_TYPE_READ_ONLY` (int)

`MYSQLI_CURSOR_TYPE_SCROLLABLE` (int)

  PHP 8.4.0 で削除されました。

`MYSQLI_STMT_ATTR_CURSOR_TYPE` (int)

`MYSQLI_STMT_ATTR_PREFETCH_ROWS` (int)

  PHP 8.4.0 で削除されました。

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

  権限テーブルをリフレッシュします。 PHP 8.4.0 で非推奨となりました。

`MYSQLI_REFRESH_LOG` (int)

  ログをフラッシュします。SQL 文 `FLUSH LOGS` を実行するのと同じです。 PHP 8.4.0 で非推奨となりました。

`MYSQLI_REFRESH_TABLES` (int)

  テーブルキャッシュをフラッシュします。SQL 文 `FLUSH TABLES` を実行するのと同じです。 PHP 8.4.0 で非推奨となりました。

`MYSQLI_REFRESH_HOSTS` (int)

  ホストキャッシュをフラッシュします。SQL 文 `FLUSH HOSTS` を実行するのと同じです。 PHP 8.4.0 で非推奨となりました。

`MYSQLI_REFRESH_REPLICA` (int)

  `MYSQLI_REFRESH_SLAVE` のエイリアスです。 PHP 8.1.0 以降で利用可能です。PHP 8.4.0 で非推奨となりました。

`MYSQLI_REFRESH_STATUS` (int)

  状態変数をリセットします。SQL 文 `FLUSH STATUS` を実行するのと同じです。 PHP 8.4.0 で非推奨となりました。

`MYSQLI_REFRESH_THREADS` (int)

  スレッドキャッシュをフラッシュします。 PHP 8.4.0 で非推奨となりました。

`MYSQLI_REFRESH_SLAVE` (int)

  レプリケーションのスレーブ側のサーバーで、 マスタサーバーの情報をリセットしてスレーブを再起動します。 SQL 文 `RESET SLAVE` を実行するのと同じです。 PHP 8.4.0 で非推奨となりました。

`MYSQLI_REFRESH_MASTER` (int)

  レプリケーションのマスタ側のサーバーで、 バイナリログインデックスにあるバイナリログファイルを削除してインデックスファイルを切り詰めます。 SQL 文 `RESET MASTER` を実行するのと同じです。 PHP 8.4.0 で非推奨となりました。

`MYSQLI_REFRESH_BACKUP_LOG` (int)
  バックアップログファイルをクローズし、再度オープンします。 PHP 8.4.0 で非推奨となりました。
`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` (int)

  トランザクションを "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)
  クエリは非同期に実行され、結果セットはすぐには返されません。 `mysqlnd` でのみ利用可能です。
`MYSQLI_ON_UPDATE_NOW_FLAG` (int)
  フィールドが更新されると、現在時刻の値が設定されます。

# ノート

若干の実装ノート

1. `MYSQL_TYPE_GEOMETRY` に対するサポートが MySQLi 拡張モジュールに PHP 5.3 で追加されました。

2. `MYSQL_TYPE_GEOMETRY` 型の項目を操作するために `libmysqlclient` および `mysqlnd` の中にそれぞれ別の異なる内部実装があることに注意してください。 一般的に言って、`mysqlnd`でのメモリ割り当ては かなり少なくなります。 例えば、`POINT` 項目が結果セットにあると、 メモリ上で `POINT` 項目を保持するには 50 バイトも 必要ないのに、`libmysqlclient` は最高 4GB の RAM を事前に割り当てるかもしれません。 `mysqlnd` を使うと、 メモリの割り当てはずっと小さく、50 バイト未満です。

# MySQLi 拡張モジュールの関数概要

mysqli メソッドの概要
mysqli クラス
OOP インターフェイス | 手続き型インターフェイス | エイリアス（使用しないこと） | 説明
--- | --- | --- | ---
プロパティ
$mysqli::affected_rows | mysqli_affected_rows() | N/A | 直前の MySQL の操作で変更された行の数を取得する
$mysqli::client_info | mysqli_get_client_info() | N/A | MySQL クライアントのバージョンを文字列で返す
$mysqli::client_version | mysqli_get_client_version() | N/A | MySQL クライアントのバージョン情報を整数で返す
$mysqli::connect_errno | mysqli_connect_errno() | N/A | 直近の接続呼び出しのエラーコードを返す
$mysqli::connect_error | mysqli_connect_error() | N/A | 直近の接続エラーの説明を文字列で返す
$mysqli::errno | mysqli_errno() | N/A | 直近の関数呼び出しのエラーコードを返す
$mysqli::error | mysqli_error() | N/A | 直近のエラーの説明を文字列で返す
$mysqli::field_count | mysqli_field_count() | N/A | 直近のクエリのカラム数を返す
$mysqli::host_info | mysqli_get_host_info() | N/A | 使用している接続の種類を文字列で返す
$mysqli::protocol_version | mysqli_get_proto_info() | N/A | 使用している MySQL プロトコルのバージョンを返す
$mysqli::server_info | mysqli_get_server_info() | N/A | MySQL サーバーのバージョンを返す
$mysqli::server_version | mysqli_get_server_version() | N/A | MySQL サーバーのバージョンを整数で返す
$mysqli::info | mysqli_info() | N/A | 直近に実行されたクエリの情報を取得する
$mysqli::insert_id | mysqli_insert_id() | N/A | 直近のクエリで使用された自動生成 ID を返す
$mysqli::sqlstate | mysqli_sqlstate() | N/A | 直前の MySQL の操作の SQLSTATE エラーを返す
$mysqli::warning_count | mysqli_warning_count() | N/A | 指定した接続の直近のクエリの警告の数を返す
メソッド
mysqli::autocommit() | mysqli_autocommit() | N/A | データベース変更の自動コミットをオンまたはオフにする
mysqli::change_user() | mysqli_change_user() | N/A | 指定したデータベース接続のユーザーを変更する
mysqli::character_set_name() | mysqli_character_set_name() | N/A | データベース接続のデフォルトの文字セットを返す
mysqli::close() | mysqli_close() | N/A | 以前にオープンしたデータベース接続を閉じる
mysqli::commit() | mysqli_commit() | N/A | 現在のトランザクションをコミットする
mysqli::__construct() | mysqli_connect() | N/A | MySQL サーバーへの新しい接続をオープンする（注意: static（つまりクラス）メソッド）
mysqli::debug() | mysqli_debug() | N/A | デバッグ操作を行う
mysqli::dump_debug_info() | mysqli_dump_debug_info() | N/A | デバッグ情報をログに出力する
mysqli::get_charset() | mysqli_get_charset() | N/A | 文字セットオブジェクトを返す
mysqli::get_connection_stats() | mysqli_get_connection_stats() | N/A | クライアント接続の統計情報を返す。mysqlnd でのみ使用可能です。
mysqli::get_client_info() | mysqli_get_client_info() | N/A | MySQL クライアントのバージョンを文字列で返す
N/A | mysqli_get_client_stats() | N/A | クライアントのプロセスごとの統計情報を返す。mysqlnd でのみ使用可能です。
mysqli::get_server_info() | mysqli_get_server_info() | N/A | MySQLi 拡張モジュールが接続している MySQL サーバーのバージョンを文字列で返す
mysqli::get_warnings() | mysqli_get_warnings() | N/A | ドキュメント化されていない
mysqli::init() | mysqli_init() | N/A | MySQLi を初期化し、mysqli_real_connect で使用するオブジェクトを返す
mysqli::kill() | mysqli_kill() | N/A | MySQL スレッドの停止をサーバーに要求する
mysqli::more_results() | mysqli_more_results() | N/A | マルチクエリからの結果がまだあるかどうかを確認する
mysqli::multi_query() | mysqli_multi_query() | N/A | データベース上でクエリを実行する
mysqli::next_result() | mysqli_next_result() | N/A | multi_query からの次の結果を準備する
mysqli::options() | mysqli_options() | mysqli_set_opt() | オプションを設定する
mysqli::ping() | mysqli_ping() | N/A | サーバー接続を ping するか、接続が切れている場合は再接続を試みる
mysqli::prepare() | mysqli_prepare() | N/A | 実行用の SQL ステートメントを準備する
mysqli::query() | mysqli_query() | N/A | データベース上でクエリを実行する
mysqli::real_connect() | mysqli_real_connect() | N/A | MySQL サーバーへの接続をオープンする
mysqli::real_escape_string(), mysqli::escape_string() | mysqli_real_escape_string() | mysqli_escape_string() | 接続の現在の文字セットを考慮して、SQL ステートメントで使用する文字列の特殊文字をエスケープする
mysqli::real_query() | mysqli_real_query() | N/A | SQL クエリを実行する
mysqli::refresh() | mysqli_refresh() | N/A | テーブルやキャッシュをフラッシュするか、レプリケーションサーバー情報をリセットする
mysqli::rollback() | mysqli_rollback() | N/A | 現在のトランザクションをロールバックする
mysqli::select_db() | mysqli_select_db() | N/A | データベースクエリのデフォルトデータベースを選択する
mysqli::set_charset() | mysqli_set_charset() | N/A | デフォルトのクライアント文字セットを設定する
mysqli::ssl_set() | mysqli_ssl_set() | N/A | SSL を使用したセキュア接続の確立に使用する
mysqli::stat() | mysqli_stat() | N/A | 現在のシステムステータスを取得する
mysqli::stmt_init() | mysqli_stmt_init() | N/A | ステートメントを初期化し、mysqli_stmt_prepare で使用するオブジェクトを返す
mysqli::store_result() | mysqli_store_result() | N/A | 直近のクエリから結果セットを転送する
mysqli::thread_id() | mysqli_thread_id() | N/A | 現在の接続のスレッド ID を返す
mysqli::thread_safe() | mysqli_thread_safe() | N/A | スレッドセーフであるかどうかを返す
mysqli::use_result() | mysqli_use_result() | N/A | 結果セットの取得を開始する

mysqli_stmt メソッドの概要
MySQL_STMT
OOP インターフェイス | 手続き型インターフェイス | エイリアス（使用しないこと） | 説明
--- | --- | --- | ---
プロパティ
$mysqli_stmt::affected_rows | mysqli_stmt_affected_rows() | N/A | 直前に実行されたステートメントで変更、削除、または挿入された行の総数を返す
$mysqli_stmt::errno | mysqli_stmt_errno() | N/A | 直近のステートメント呼び出しのエラーコードを返す
$mysqli_stmt::error | mysqli_stmt_error() | N/A | 直近のステートメントエラーの説明を文字列で返す
$mysqli_stmt::field_count | mysqli_stmt_field_count() | N/A | 指定されたステートメントのフィールド数を返す - ドキュメント化されていない
$mysqli_stmt::insert_id | mysqli_stmt_insert_id() | N/A | 直前の INSERT 操作で生成された ID を取得する
$mysqli_stmt::num_rows | mysqli_stmt_num_rows() | N/A | ステートメントの結果セットの行数を返す
$mysqli_stmt::param_count | mysqli_stmt_param_count() | N/A | 指定されたステートメントのパラメータ数を返す
$mysqli_stmt::sqlstate | mysqli_stmt_sqlstate() | N/A | 直前のステートメント操作の SQLSTATE エラーを返す
メソッド
mysqli_stmt::attr_get() | mysqli_stmt_attr_get() | N/A | ステートメントアトリビュートの現在の値を取得する
mysqli_stmt::attr_set() | mysqli_stmt_attr_set() | N/A | プリペアドステートメントの動作を変更する
mysqli_stmt::bind_param() | mysqli_stmt_bind_param() | N/A | プリペアドステートメントのパラメータに変数をバインドする
mysqli_stmt::bind_result() | mysqli_stmt_bind_result() | N/A | 結果を格納するためにプリペアドステートメントに変数をバインドする
mysqli_stmt::close() | mysqli_stmt_close() | N/A | プリペアドステートメントを閉じる
mysqli_stmt::data_seek() | mysqli_stmt_data_seek() | N/A | ステートメントの結果セットの任意の行にシークする
mysqli_stmt::execute() | mysqli_stmt_execute() | mysqli_execute() | プリペアドクエリを実行する
mysqli_stmt::fetch() | mysqli_stmt_fetch() | N/A | プリペアドステートメントの結果をバインドされた変数に取得する
mysqli_stmt::free_result() | mysqli_stmt_free_result() | N/A | 指定されたステートメントハンドルの格納された結果メモリを解放する
mysqli_stmt::get_result() | mysqli_stmt_get_result() | N/A | プリペアドステートメントから結果セットを取得する。mysqlnd でのみ使用可能です。
mysqli_stmt::get_warnings() | mysqli_stmt_get_warnings() | N/A | ドキュメント化されていない
mysqli_stmt::more_results() | mysqli_stmt_more_results() | N/A | マルチクエリからの結果がまだあるかどうかを確認する
mysqli_stmt::next_result() | mysqli_stmt_next_result() | N/A | マルチクエリからの次の結果を読み取る
mysqli_stmt::num_rows() | mysqli_stmt_num_rows() | N/A | プロパティ $mysqli_stmt::num_rows も参照
mysqli_stmt::prepare() | mysqli_stmt_prepare() | N/A | 実行用の SQL ステートメントを準備する
mysqli_stmt::reset() | mysqli_stmt_reset() | N/A | プリペアドステートメントをリセットする
mysqli_stmt::result_metadata() | mysqli_stmt_result_metadata() | N/A | プリペアドステートメントから結果セットのメタデータを返す
mysqli_stmt::send_long_data() | mysqli_stmt_send_long_data() | N/A | データをブロック単位で送信する
mysqli_stmt::store_result() | mysqli_stmt_store_result() | N/A | プリペアドステートメントから結果セットを転送する

mysqli_result メソッドの概要
mysqli_result
OOP インターフェイス | 手続き型インターフェイス | エイリアス（使用しないこと） | 説明
--- | --- | --- | ---
プロパティ
$mysqli_result::current_field | mysqli_field_tell() | N/A | 結果ポインタの現在のフィールドオフセットを取得する
$mysqli_result::field_count | mysqli_num_fields() | N/A | 結果のフィールド数を取得する
$mysqli_result::lengths | mysqli_fetch_lengths() | N/A | 結果セットの現在の行のカラムの長さを返す
$mysqli_result::num_rows | mysqli_num_rows() | N/A | 結果の行数を取得する
メソッド
mysqli_result::data_seek() | mysqli_data_seek() | N/A | 結果の任意の行に結果ポインタを移動する
mysqli_result::fetch_all() | mysqli_fetch_all() | N/A | すべての結果行を取得し、結果セットを連想配列、数値配列、またはその両方として返す。mysqlnd でのみ使用可能です。
mysqli_result::fetch_array() | mysqli_fetch_array() | N/A | 結果の行を連想配列、数値配列、またはその両方として取得する
mysqli_result::fetch_assoc() | mysqli_fetch_assoc() | N/A | 結果の行を連想配列として取得する
mysqli_result::fetch_column() | mysqli_fetch_column() | N/A | 結果セットの次の行から単一のカラムを取得する
mysqli_result::fetch_field_direct() | mysqli_fetch_field_direct() | N/A | 単一フィールドのメタデータを取得する
mysqli_result::fetch_field() | mysqli_fetch_field() | N/A | 結果セットの次のフィールドを返す
mysqli_result::fetch_fields() | mysqli_fetch_fields() | N/A | 結果セットのフィールドを表すオブジェクトの配列を返す
mysqli_result::fetch_object() | mysqli_fetch_object() | N/A | 結果セットの現在の行をオブジェクトとして返す
mysqli_result::fetch_row() | mysqli_fetch_row() | N/A | 結果の行を列挙配列として取得する
mysqli_result::field_seek() | mysqli_field_seek() | N/A | 結果ポインタを指定したフィールドオフセットに設定する
mysqli_result::free(), mysqli_result::close, mysqli_result::free_result | mysqli_free_result() | N/A | 結果に関連付けられたメモリを解放する

mysqli_driver メソッドの概要
MySQL_Driver
OOP インターフェイス | 手続き型インターフェイス | エイリアス（使用しないこと） | 説明
--- | --- | --- | ---
プロパティ
$mysqli_driver::mysqli_report | mysqli_report() | N/A | mysqli のエラー報告モードを設定する
メソッド
mysqli_driver::embedded_server_end() | mysqli_embedded_server_end() | N/A | ドキュメント化されていない
mysqli_driver::embedded_server_start() | mysqli_embedded_server_start() | N/A | ドキュメント化されていない

> 注意:

> エイリアス関数は後方互換性のためにのみ提供されています。 新しいプロジェクトでは使用しないでください。

# 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 function __construct(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
)
public function autocommit(bool `$enable`): bool
public function begin_transaction(int `$flags` = 0, ?string `$name` = `null`): bool
public function change_user(string `$username`, #[\SensitiveParameter] string `$password`, ?string `$database`): bool
public function character_set_name(): string
public function close(): true
public function commit(int `$flags` = 0, ?string `$name` = `null`): bool
public function connect(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
): bool
public function debug(string `$options`): true
public function dump_debug_info(): bool
public function execute_query(string `$query`, ?array `$params` = `null`): mysqli_result|bool
public function get_charset(): ?object
#[\Deprecated]
public function get_client_info(): string
public function get_connection_stats(): array
public function get_server_info(): string
public function get_warnings(): mysqli_warning|false
#[\Deprecated]
public function init(): ?bool
#[\Deprecated]
public function kill(int `$process_id`): bool
public function more_results(): bool
public function multi_query(string `$query`): bool
public function next_result(): bool
public function options(int `$option`, string|int `$value`): bool
#[\Deprecated]
public function ping(): bool
public static function poll(
?array `&$read`,
?array `&$error`,
array `&$reject`,
int `$seconds`,
int `$microseconds` = 0
): int|false
public function prepare(string `$query`): mysqli_stmt|false
public function query(string `$query`, int `$result_mode` = `MYSQLI_STORE_RESULT`): mysqli_result|bool
public function 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 function real_escape_string(string `$string`): string
public function real_query(string `$query`): bool
public function reap_async_query(): mysqli_result|bool
#[\Deprecated]
public function refresh(int `$flags`): bool
public function release_savepoint(string `$name`): bool
public function rollback(int `$flags` = 0, ?string `$name` = `null`): bool
public function savepoint(string `$name`): bool
public function select_db(string `$database`): bool
public function set_charset(string `$charset`): bool
public function ssl_set(
?string `$key`,
?string `$certificate`,
?string `$ca_certificate`,
?string `$ca_path`,
?string `$cipher_algos`
): true
public function stat(): string|false
public function stmt_init(): mysqli_stmt|false
public function store_result(int `$mode` = 0): mysqli_result|false
public function thread_safe(): bool
public function use_result(): mysqli_result|false
}

# mysqli::$affected_rows

# mysqli_affected_rows

(PHP 5, PHP 7, PHP 8)

mysqli::$affected_rows -- mysqli_affected_rows — 直前の MySQL の操作で変更された行の数を得る

### 説明

オブジェクト指向型

int|string $mysqli->affected_rows;

手続き型

function 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::autocommit

# mysqli_autocommit

(PHP 5, PHP 7, PHP 8)

mysqli::autocommit -- mysqli_autocommit — データベース更新の自動コミットをオンまたはオフにする

### 説明

オブジェクト指向型

public function mysqli::autocommit(bool `$enable`): bool

手続き型

function 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::begin_transaction

# mysqli_begin_transaction

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

mysqli::begin_transaction -- mysqli_begin_transaction — トランザクションを開始する

### 説明

オブジェクト指向型

public function mysqli::begin_transaction(int `$flags` = 0, ?string `$name` = `null`): bool

手続き型:

function 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::change_user

# mysqli_change_user

(PHP 5, PHP 7, PHP 8)

mysqli::change_user -- mysqli_change_user — データベース接続のユーザー名を変更する

### 説明

オブジェクト指向型

public function mysqli::change_user(string `$username`, #[\SensitiveParameter] string `$password`, ?string `$database`): bool

手続き型

function mysqli_change_user(
mysqli `$mysql`,
string `$username`,
#[\SensitiveParameter] string `$password`,
?string `$database`
): bool

指定された認証情報を使って、指定されたデータベースに接続しようと試みます。

このメソッドは新しい接続が確立できなかった場合に、現在の接続を切断しません。 その点で mysqli::connect() と異なります。

ユーザーを正しく変更するには、`username` と `password` 引数を正しく渡す必要があります。 またそのユーザーが対象のデータベースに対する適切なパーミッションを 持っている必要があります。どんな理由であれ、認証に失敗するとカレントユーザーの 認証が継続されます。

### パラメータ

`link`
  手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。
`username`

  MySQL のユーザー名。

`password`

  MySQL のパスワード。

`database`

  データベース名。 `null` または空文字列を指定した場合、 デフォルトのデータベースを指定しない状態でサーバーとの接続がオープンされます。

### 戻り値

成功した場合に `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", "test");

    $mysqli->query("SET @a:=1");

    $mysqli->change_user("my_user", "my_password", "world");

    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("Default database: %s\n", $row[0]);

    $result = $mysqli->query("SELECT @a");
    $row = $result->fetch_row();
    if ($row[0] === null) {
        printf("Value of variable a is NULL\n");
    }

手続き型

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "my_user", "my_password", "test");

    mysqli_query($link, "SET @a:=1");

    mysqli_change_user($link, "my_user", "my_password", "world");

    $result = mysqli_query($link, "SELECT DATABASE()");
    $row = mysqli_fetch_row($result);
    printf("Default database: %s\n", $row[0]);

    $result = mysqli_query($link, "SELECT @a");
    $row = mysqli_fetch_row($result);
    if ($row[0] === null) {
        printf("Value of variable a is NULL\n");
    }

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

    Default database: world
    Value of variable a is NULL

例2 `database` が `null` の場合、 デフォルトのデータベースが選択されない状態で接続がオープンされる

オブジェクト指向型

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "test");

    $mysqli->change_user("my_user", "my_password", null);

    $result = $mysqli->query("SELECT DATABASE()");
    $row = $result->fetch_row();
    printf("Default database: %s\n", $row[0]);

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

    Default database:

### 注意

> 注意:

> このコマンドを使用すると、常に、カレントのデータベース接続は あたかも完全に新しいデータベース接続であるかのようになります。 これにより、全てのアクティブなトランザクションはロールバックされ、 一時テーブルは全てクローズされ、ロックされたテーブルはすべて 開放されます。

### 参考

- mysqli_connect() - mysqli::__construct のエイリアス
- mysqli_select_db() - クエリを実行するためのデフォルトのデータベースを選択する

# mysqli::character_set_name

# mysqli_character_set_name

(PHP 5, PHP 7, PHP 8)

mysqli::character_set_name -- mysqli_character_set_name — データベース接続の現在の文字コードセットを返す

### 説明

オブジェクト指向型

public function mysqli::character_set_name(): string

手続き型

function 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::close

# mysqli_close

(PHP 5, PHP 7, PHP 8)

mysqli::close -- mysqli_close — 事前にオープンしているデータベース接続を閉じる

### 説明

オブジェクト指向型

public function mysqli::close(): true

手続き型

function 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::commit

# mysqli_commit

(PHP 5, PHP 7, PHP 8)

mysqli::commit -- mysqli_commit — 現在のトランザクションをコミットする

### 説明

オブジェクト指向型

public function mysqli::commit(int `$flags` = 0, ?string `$name` = `null`): bool

手続き型

function 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::$connect_errno

# mysqli_connect_errno

(PHP 5, PHP 7, PHP 8)

mysqli::$connect_errno -- mysqli_connect_errno — 直近の接続コールに関するエラーコードを返す

### 説明

オブジェクト指向型

int $mysqli->connect_errno;

手続き型

function 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_error

# mysqli_connect_error

(PHP 5, PHP 7, PHP 8)

mysqli::$connect_error -- mysqli_connect_error — 直近の接続エラーの説明を返す

### 説明

オブジェクト指向型

?string $mysqli->connect_error;

手続き型

function 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 エラーを返す

# mysqli::__construct

# mysqli::connect

# mysqli_connect

(PHP 5, PHP 7, PHP 8)

mysqli::__construct -- mysqli::connect -- mysqli_connect — 新規に MySQL サーバーへの接続をオープンする

### 説明

オブジェクト指向型

public function mysqli::__construct(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
)
public function mysqli::connect(
?string `$hostname` = `null`,
?string `$username` = `null`,
#[\SensitiveParameter] ?string `$password` = `null`,
?string `$database` = `null`,
?int `$port` = `null`,
?string `$socket` = `null`
): bool

手続き型

function 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::__construct() は、接続が成功するかしないかに関係なく、 MySQL サーバーへの接続を表すオブジェクトを常に返します。

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::debug

# mysqli_debug

(PHP 5, PHP 7, PHP 8)

mysqli::debug -- mysqli_debug — デバッグ操作を行う

### 説明

オブジェクト指向型

public function mysqli::debug(string `$options`): true

手続き型

function 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::dump_debug_info

# mysqli_dump_debug_info

(PHP 5, PHP 7, PHP 8)

mysqli::dump_debug_info -- mysqli_dump_debug_info — デバッグ情報をログに出力する

### 説明

オブジェクト指向型

public function mysqli::dump_debug_info(): bool

手続き型

function mysqli_dump_debug_info(mysqli `$mysql`): bool

この関数は SUPER 権限を持ったユーザーによって実行されるされることを 想定しており、`link` で指定した接続に関連する MySQL サーバーのデバッグ情報をログに出力します。

### パラメータ

`link`
  手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- mysqli_debug() - デバッグ操作を行う

# mysqli::$errno

# mysqli_errno

(PHP 5, PHP 7, PHP 8)

mysqli::$errno -- mysqli_errno — 直近の関数コールによるエラーコードを返す

### 説明

オブジェクト指向型

int $mysqli->errno;

手続き型

function 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::$error

# mysqli_error

(PHP 5, PHP 7, PHP 8)

mysqli::$error -- mysqli_error — 直近のエラーの内容を文字列で返す

### 説明

オブジェクト指向型

string $mysqli->error;

手続き型

function 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_list

# mysqli_error_list

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

mysqli::$error_list -- mysqli_error_list — 直近で実行したコマンドからのエラーの一覧を返す

### 説明

オブジェクト指向型

array $mysqli->error_list;

手続き型

function 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 エラーを返す

# mysqli::execute_query

# mysqli_execute_query

(PHP 8 >= 8.2.0)

mysqli::execute_query -- mysqli_execute_query — SQL文を準備し、変数をバインドし、実行する

### 説明

オブジェクト指向型

public function mysqli::execute_query(string `$query`, ?array `$params` = `null`): mysqli_result|bool

手続き型

function 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::$field_count

# mysqli_field_count

(PHP 5, PHP 7, PHP 8)

mysqli::$field_count -- mysqli_field_count — 直近のクエリのカラムの数を返す

### 説明

オブジェクト指向型

int $mysqli->field_count;

手続き型

function 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::get_charset

# mysqli_get_charset

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

mysqli::get_charset -- mysqli_get_charset — 文字セットオブジェクトを返す

### 説明

オブジェクト指向型

public function mysqli::get_charset(): ?object

手続き型

function mysqli_get_charset(mysqli `$mysql`): ?object

文字セットオブジェクトを返します。 これは、現在アクティブな文字セットについてのプロパティを提供します。

### パラメータ

`link`
  手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

### 戻り値

この関数は、以下のプロパティを持つ文字セットオブジェクトを返します。

`charset`

  文字セット名

`collation`

  照合規則名

`dir`

  文字セットの説明を取得したディレクトリ。組み込みの文字セットについては ""

`min_length`

  最小の文字の長さ (バイト数)

`max_length`

  最大の文字の長さ (バイト数)

`number`

  内部文字セット番号

`state`

  PHP 8.2.0 以降、常に `1`

### 例

例1 mysqli::get_charset() の例

オブジェクト指向型

    <?php
      $db = mysqli_init();
      $db->real_connect("localhost","root","","test");
      $db->set_charset('latin1');
      var_dump($db->get_charset());
    ?>

手続き型

    <?php
      $db = mysqli_init();
      mysqli_real_connect($db, "localhost","root","","test");
      mysqli_set_charset($db, 'latin1');
      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(1)
    }

### 参考

- mysqli_character_set_name() - データベース接続の現在の文字コードセットを返す
- mysqli_set_charset() - クライアントの文字セットを設定する

# 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;
#[\Deprecated]
public function mysqli::get_client_info(): string

手続き型

function 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 サーバーのバージョンを整数値で返す

# 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;

手続き型

function 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::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 function mysqli::get_connection_stats(): array

手続き型

function 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::$host_info

# mysqli_get_host_info

(PHP 5, PHP 7, PHP 8)

mysqli::$host_info -- mysqli_get_host_info — 使用している接続の型を文字列で返す

### 説明

オブジェクト指向型

string $mysqli->host_info;

手続き型

function 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 プロトコルのバージョンを返す

# 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;

手続き型

function 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() - 使用している接続の型を文字列で返す

# 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 function mysqli::get_server_info(): string

手続き型

function 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 サーバーのバージョンを整数値で返す

# 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;

手続き型

function 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 サーバーのバージョンを返す

# mysqli::get_warnings

# mysqli_get_warnings

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

mysqli::get_warnings -- mysqli_get_warnings — SHOW WARNINGS の結果を取得する

### 説明

オブジェクト指向型

public function mysqli::get_warnings(): mysqli_warning|false

手続き型

function mysqli_get_warnings(mysqli `$mysql`): mysqli_warning|false

mysqli_warning で構成された単方向リンクリストを返します。 警告がない場合は `false` を返します。 リスト中のオブジェクトはそれぞれ、 `SHOW WARNINGS` の単一行の結果からなります。 mysqli_warning::next() をコールすると、次の行からオブジェクトを埋めます。

> 注意: 警告メッセージを取得するには、 この関数ではなく、SQLコマンド `SHOW WARNINGS [limit row_count]` を使うことを推奨します。

警告

リンクリストは、巻き戻したり、再取得したりはできません。

### パラメータ

`link`
  手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

### 戻り値

mysqli_warning からなる、 単方向リンクリストを返します。 警告がない場合は、`false` を返します。

### 例

例1 全ての警告を取得するために連結リストを走査する

オブジェクト指向型

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("SELECT 1/0, CAST('NULL' AS UNSIGNED)");

    if ($mysqli->warning_count > 0) {
        $warning = $mysqli->get_warnings();
        if ($warning !== false) {
            do {
                printf("Error number: %s\n", $warning->errno);
                printf("Message: %s\n", $warning->message);
            } while ($warning->next());
        }
    }

手続き型

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_connect("localhost", "user", "password", "test");

    mysqli_query($link, "SELECT 1/0, CAST('NULL' AS UNSIGNED)");

    if (mysqli_warning_count($link) > 0) {
        $warning = mysqli_get_warnings($link);
        if ($warning !== false) {
            do {
                printf("Error number: %s\n", $warning->errno);
                printf("Message: %s\n", $warning->message);
            } while ($warning->next());
        }
    }

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

    Error number: 1365
    Message: Division by 0
    Error number: 1292
    Message: Truncated incorrect INTEGER value: 'NULL'

# mysqli::$info

# mysqli_info

(PHP 5, PHP 7, PHP 8)

mysqli::$info -- mysqli_info — 直近に実行されたクエリの情報を取得する

### 説明

オブジェクト指向型

?string $mysqli->info;

手続き型

function 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::init

# mysqli_init

(PHP 5, PHP 7, PHP 8)

mysqli::init -- mysqli_init — MySQLi を初期化し、mysqli_real_connect() で使うオブジェクトを返す

### 説明

オブジェクト指向型

#[\Deprecated]
public function mysqli::init(): ?bool

手続き型

function 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 のエイリアス

# 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;

手続き型

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

# mysqli::kill

# mysqli_kill

(PHP 5, PHP 7, PHP 8)

mysqli::kill -- mysqli_kill — サーバーに MySQL スレッドの停止を問い合わせる

警告

この関数は PHP 8.4.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

オブジェクト指向型

#[\Deprecated]
public function mysqli::kill(int `$process_id`): bool

手続き型

#[\Deprecated]
function 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 が代わりにスローされます。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | mysqli::kill() と mysqli_kill() は非推奨となりました。代わりに `KILL` SQL コマンドを使用してください。

### 例

例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::more_results

# mysqli_more_results

(PHP 5, PHP 7, PHP 8)

mysqli::more_results -- mysqli_more_results — マルチクエリからの結果がまだ残っているかどうかを調べる

### 説明

オブジェクト指向型

public function mysqli::more_results(): bool

手続き型

function 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::multi_query

# mysqli_multi_query

(PHP 5, PHP 7, PHP 8)

mysqli::multi_query -- mysqli_multi_query — データベース上でひとつ以上のクエリを実行する

### 説明

オブジェクト指向型

public function mysqli::multi_query(string `$query`): bool

手続き型

function mysqli_multi_query(mysqli `$mysql`, string `$query`): bool

セミコロンで連結されたひとつまたは複数のクエリを実行します。

警告

# セキュリティ上の注意: SQLインジェクション

クエリに入力値を含める場合は、プリペアドステートメント を使うべきです。使わない場合、データを適切にフォーマットし、全ての文字列は mysqli_real_escape_string() を使ってエスケープしなければいけません。

クエリはひとつの呼び出しでデータベースに送信され、順番に処理されます。 mysqli_multi_query() は PHP に制御を戻す前に、最初のクエリの実行が完了するのを待ちます。 その間、MySQL サーバーは PHP とは非同期に残りのクエリの処理を続け、 結果を取得できる状態にします。

複数のクエリを処理するために、 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() - マルチクエリからの結果がまだ残っているかどうかを調べる

# mysqli::next_result

# mysqli_next_result

(PHP 5, PHP 7, PHP 8)

mysqli::next_result -- mysqli_next_result — multi_query の、次の結果を準備する

### 説明

オブジェクト指向型

public function mysqli::next_result(): bool

手続き型

function 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::options

# mysqli_options

(PHP 5, PHP 7, PHP 8)

mysqli::options -- mysqli_options — オプションを設定する

### 説明

オブジェクト指向型

public function mysqli::options(int `$option`, string|int `$value`): bool

手続き型

function 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_OPT_LOAD_DATA_LOCAL_DIR` | `LOAD DATA 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 ベースの認証で使います。
  `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` | サーバーの証明書を検証するかしないかを指定します。
  `MYSQLI_OPT_CAN_HANDLE_EXPIRED_PASSWORDS` | クライアントが期限切れのパスワードを受け入れるかどうかを指定します。
  `1` | ネットワーク通信の圧縮を使用するかどうかを指定します。

`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::ping

# mysqli_ping

(PHP 5, PHP 7, PHP 8)

mysqli::ping -- mysqli_ping — サーバーとの接続をチェックし、もし切断されている場合は再接続を試みる

警告

この関数は PHP 8.4.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

オブジェクト指向型

#[\Deprecated]
public function mysqli::ping(): bool

手続き型

#[\Deprecated]
function 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 が代わりにスローされます。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | mysqli::ping() と mysqli_ping() は非推奨となりました。 `reconnect` 機能は PHP 8.2.0 で廃止されたため、この関数はもはや必要ありません。

### 例

例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::poll

# mysqli_poll

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::poll -- mysqli_poll — 接続を問い合わせる

### 説明

オブジェクト指向型

public static function mysqli::poll(
?array `&$read`,
?array `&$error`,
array `&$reject`,
int `$seconds`,
int `$microseconds` = 0
): int|false

手続き型

function 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() - 非同期クエリから結果を取得する

# mysqli::prepare

# mysqli_prepare

(PHP 5, PHP 7, PHP 8)

mysqli::prepare -- mysqli_prepare — 実行するための SQL文 を準備する

### 説明

オブジェクト指向型

public function mysqli::prepare(string `$query`): mysqli_stmt|false

手続き型

function 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::query

# mysqli_query

(PHP 5, PHP 7, PHP 8)

mysqli::query -- mysqli_query — データベース上でクエリを実行する

### 説明

オブジェクト指向型

public function mysqli::query(string `$query`, int `$result_mode` = `MYSQLI_STORE_RESULT`): mysqli_result|bool

手続き型

function 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() - 結果に関連付けられたメモリを開放する

# mysqli::real_connect

# mysqli_real_connect

(PHP 5, PHP 7, PHP 8)

mysqli::real_connect -- mysqli_real_connect — mysql サーバーとの接続をオープンする

### 説明

オブジェクト指向型

public function 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

手続き型

function 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() が作成した接続オブジェクトが必要です。

- `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_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = mysqli_init();

    $mysqli->options(MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0');
    $mysqli->options(MYSQLI_OPT_CONNECT_TIMEOUT, 5);

    $mysqli->real_connect('localhost', 'my_user', 'my_password', 'my_db', null, null, MYSQLI_CLIENT_COMPRESS|MYSQLI_CLIENT_FOUND_ROWS);

    echo 'Success... ' . $mysqli->host_info . "\n";

オブジェクト指向型 で mysqli クラスを継承する例

    <?php

    class foo_mysqli extends mysqli {
        public function __construct($host, $user, $pass, $db)
        {
            parent::__construct();

            parent::options(MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0');
            parent::options(MYSQLI_OPT_CONNECT_TIMEOUT, 5);

            parent::real_connect($host, $user, $pass, $db, null, null, MYSQLI_CLIENT_COMPRESS|MYSQLI_CLIENT_FOUND_ROWS);
        }
    }

    $db = new foo_mysqli('localhost', 'my_user', 'my_password', 'my_db');

    echo 'Success... ' . $db->host_info . "\n";

手続き型

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $link = mysqli_init();

    mysqli_options($link, MYSQLI_INIT_COMMAND, 'SET AUTOCOMMIT = 0');
    mysqli_options($link, MYSQLI_OPT_CONNECT_TIMEOUT, 5);

    mysqli_real_connect($link, 'localhost', 'my_user', 'my_password', 'my_db', null, null, MYSQLI_CLIENT_COMPRESS|MYSQLI_CLIENT_FOUND_ROWS);

    echo 'Success... ' . mysqli_get_host_info($link) . "\n";

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

    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() - 事前にオープンしているデータベース接続を閉じる

# mysqli::real_escape_string

# mysqli_real_escape_string

(PHP 5, PHP 7, PHP 8)

mysqli::real_escape_string -- mysqli_real_escape_string — 接続の現在の文字セットを考慮して、SQL 文で使用する文字列の特殊文字をエスケープする

### 説明

オブジェクト指向型

public function mysqli::real_escape_string(string `$string`): string

手続き型

function 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() - クライアントの文字セットを設定する

# mysqli::real_query

# mysqli_real_query

(PHP 5, PHP 7, PHP 8)

mysqli::real_query -- mysqli_real_query — SQL クエリを実行する

### 説明

オブジェクト指向型

public function mysqli::real_query(string `$query`): bool

手続き型

function 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::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 function mysqli::reap_async_query(): mysqli_result|bool

手続き型

function 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::refresh

# mysqli_refresh

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli::refresh -- mysqli_refresh — リフレッシュする

警告

この関数は PHP 8.4.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

オブジェクト指向型

#[\Deprecated]
public function mysqli::refresh(int `$flags`): bool

手続き型

#[\Deprecated]
function mysqli_refresh(mysqli `$mysql`, int `$flags`): bool

テーブルやキャッシュのフラッシュ、あるいはレプリケーションサーバー情報のリセットを行います。

### パラメータ

`link`
  手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。
`flags`

  リフレッシュのオプションを定数 MYSQLI_REFRESH_* で指定します。定数の意味は MySQLi 定数 のドキュメントを参照ください。

  公式ドキュメントの » MySQL Refresh も参照ください。

### 戻り値

リフレッシュに成功した場合に `true`、それ以外の場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | mysqli::refresh() と mysqli_refresh() は非推奨となりました。代わりに `FLUSH` SQL コマンドを使用してください。

### 参考

- mysqli_poll() - 接続を問い合わせる

# mysqli::release_savepoint

# mysqli_release_savepoint

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

mysqli::release_savepoint -- mysqli_release_savepoint — 現在のトランザクションのセーブポイント群から、指定した名前のセーブポイントを削除する

### 説明

オブジェクト指向型

public function mysqli::release_savepoint(string `$name`): bool

手続き型:

function 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::rollback

# mysqli_rollback

(PHP 5, PHP 7, PHP 8)

mysqli::rollback -- mysqli_rollback — 現在のトランザクションをロールバックする

### 説明

オブジェクト指向型

public function mysqli::rollback(int `$flags` = 0, ?string `$name` = `null`): bool

手続き型

function 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::savepoint

# mysqli_savepoint

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

mysqli::savepoint -- mysqli_savepoint — トランザクションのセーブポイントを設定する

### 説明

オブジェクト指向型

public function mysqli::savepoint(string `$name`): bool

手続き型:

function mysqli_savepoint(mysqli `$mysql`, string `$name`): bool

この関数は、 `$mysqli->query("SAVEPOINT `$name`");` を実行することと同等です。

### パラメータ

`link`
  手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。
`name`

  セーブポイントの識別子

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- mysqli_release_savepoint() - 現在のトランザクションのセーブポイント群から、指定した名前のセーブポイントを削除する

# mysqli::select_db

# mysqli_select_db

(PHP 5, PHP 7, PHP 8)

mysqli::select_db -- mysqli_select_db — クエリを実行するためのデフォルトのデータベースを選択する

### 説明

オブジェクト指向型

public function mysqli::select_db(string `$database`): bool

手続き型

function 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::set_charset

# mysqli_set_charset

(PHP 5 >= 5.0.5, PHP 7, PHP 8)

mysqli::set_charset -- mysqli_set_charset — クライアントの文字セットを設定する

### 説明

オブジェクト指向型

public function mysqli::set_charset(string `$charset`): bool

手続き型

function 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

### 注意

> 注意:

> 文字セットを変更するにはこの方法を使うことを推奨します。 mysqli_query() で (`SET NAMES utf8` などとして) 設定する方法はお勧めできません。詳細は MySQL の文字セットの概念 を参照ください。

### 参考

- mysqli_character_set_name() - データベース接続の現在の文字コードセットを返す
- mysqli_real_escape_string() - 接続の現在の文字セットを考慮して、SQL 文で使用する文字列の特殊文字をエスケープする
- MySQL 文字セットのコンセプト
- » MySQL がサポートする文字セットの一覧

# mysqli::$sqlstate

# mysqli_sqlstate

(PHP 5, PHP 7, PHP 8)

mysqli::$sqlstate -- mysqli_sqlstate — 直前の MySQL の操作での SQLSTATE エラーを返す

### 説明

オブジェクト指向型

string $mysqli->sqlstate;

手続き型

function 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() - 直近のエラーの内容を文字列で返す

# mysqli::ssl_set

# mysqli_ssl_set

(PHP 5, PHP 7, PHP 8)

mysqli::ssl_set -- mysqli_ssl_set — SSL を使用したセキュアな接続を確立する

### 説明

オブジェクト指向型

public function mysqli::ssl_set(
?string `$key`,
?string `$certificate`,
?string `$ca_certificate`,
?string `$ca_path`,
?string `$cipher_algos`
): true

手続き型

function 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::stat

# mysqli_stat

(PHP 5, PHP 7, PHP 8)

mysqli::stat -- mysqli_stat — 現在のシステム状態を取得する

### 説明

オブジェクト指向型

public function mysqli::stat(): string|false

手続き型

function 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_init

# mysqli_stmt_init

(PHP 5, PHP 7, PHP 8)

mysqli::stmt_init -- mysqli_stmt_init — ステートメントを初期化し、mysqli_stmt_prepare で使用するオブジェクトを返す

### 説明

オブジェクト指向型

public function mysqli::stmt_init(): mysqli_stmt|false

手続き型

function 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::store_result

# mysqli_store_result

(PHP 5, PHP 7, PHP 8)

mysqli::store_result -- mysqli_store_result — 直近のクエリから結果セットを転送する

### 説明

オブジェクト指向型

public function mysqli::store_result(int `$mode` = 0): mysqli_result|false

手続き型

function 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 が代わりにスローされます。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `mode` パラメータの指定は非推奨となりました。 PHP 8.1 以降では、このパラメータを指定しても意味はありません。

### 例

mysqli_multi_query() を参照ください。

### 注意

> 注意:

> クエリ結果が使用するメモリを mysqli_free_result() 関数で開放するのは、どんな場合でも大切です。しかし、大きい結果セットを mysqli_store_result() で転送した際は、特にこれが 重要となります。

### 参考

- mysqli_real_query() - SQL クエリを実行する
- mysqli_use_result() - 結果セットの取得を開始する

# mysqli::$thread_id

# mysqli_thread_id

(PHP 5, PHP 7, PHP 8)

mysqli::$thread_id -- mysqli_thread_id — 現在の接続のスレッド ID を返す

### 説明

オブジェクト指向型

int $mysqli->thread_id;

手続き型

function 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_safe

# mysqli_thread_safe

(PHP 5, PHP 7, PHP 8)

mysqli::thread_safe -- mysqli_thread_safe — スレッドセーフであるかどうかを返す

### 説明

オブジェクト指向型

public function mysqli::thread_safe(): bool

手続き型

function mysqli_thread_safe(): bool

クライアントライブラリがスレッドセーフでコンパイルされているかどうかを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

クライアントライブラリがスレッドセーフの場合に `true`、 そうでない場合に `false` を返します。

# mysqli::use_result

# mysqli_use_result

(PHP 5, PHP 7, PHP 8)

mysqli::use_result -- mysqli_use_result — 結果セットの取得を開始する

### 説明

オブジェクト指向型

public function mysqli::use_result(): mysqli_result|false

手続き型

function 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::$warning_count

# mysqli_warning_count

(PHP 5, PHP 7, PHP 8)

mysqli::$warning_count -- mysqli_warning_count — 直近の実行されたクエリから発生した警告の数を返す

### 説明

オブジェクト指向型

int $mysqli->warning_count;

手続き型

function mysqli_warning_count(mysqli `$mysql`): int

直近の実行されたクエリから発生した警告の数を返します。

> 注意: 警告の内容を取得するには、以下のSQLコマンドを使用します: `SHOW WARNINGS [limit row_count]`

### パラメータ

`link`
  手続き型のみ: mysqli_connect() あるいは mysqli_init() が返す mysqliオブジェクト。

### 戻り値

警告の数を返します。警告がなかった場合はゼロを返します。

### 例

例1 $mysqli->warning_count の例

オブジェクト指向型

    <?php

    mysqli_report(MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT);
    $mysqli = new mysqli("localhost", "my_user", "my_password", "world");

    $mysqli->query("SELECT 42/0");

    if ($mysqli->warning_count > 0) {
        $result = $mysqli->query("SHOW WARNINGS");
        $row = $result->fetch_row();
        printf("%s (%d): %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, "SELECT 42/0");

    if (mysqli_warning_count($link) > 0) {
        $result = mysqli_query($link, "SHOW WARNINGS");
        $row = mysqli_fetch_row($result);
        printf("%s (%d): %s\n", $row[0], $row[1], $row[2]);
    }

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

    Warning (1365): Division by 0

### 参考

- mysqli_errno() - 直近の関数コールによるエラーコードを返す
- mysqli_error() - 直近のエラーの内容を文字列で返す
- mysqli_sqlstate() - 直前の MySQL の操作での SQLSTATE エラーを返す

## 目次

- 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 クラス

(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 function __construct(mysqli `$mysql`, ?string `$query` = `null`)
public function attr_get(int `$attribute`): int
public function attr_set(int `$attribute`, int `$value`): bool
public function bind_param(string `$types`, mixed `&$var`, mixed `&...$vars`): bool
public function bind_result(mixed `&$var`, mixed `&...$vars`): bool
public function close(): true
public function data_seek(int `$offset`): void
public function execute(?array `$params` = `null`): bool
public function fetch(): ?bool
public function free_result(): void
public function get_result(): mysqli_result|false
public function get_warnings(): mysqli_warning|false
public function more_results(): bool
public function next_result(): bool
public function num_rows(): int|string
public function prepare(string `$query`): bool
public function reset(): bool
public function result_metadata(): mysqli_result|false
public function send_long_data(int `$param_num`, string `$data`): bool
public function store_result(): bool
}

## プロパティ

id

  プリペアドステートメントの ID を保持します。

# 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;

手続き型

function 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::attr_get

# mysqli_stmt_attr_get

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::attr_get -- mysqli_stmt_attr_get — ステートメントの属性の現在の値を取得する

### 説明

オブジェクト指向型

public function mysqli_stmt::attr_get(int `$attribute`): int

手続き型

function mysqli_stmt_attr_get(mysqli_stmt `$statement`, int `$attribute`): int

ステートメントの属性の現在の値を取得します。

### パラメータ

`stmt`
  手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。
`attribute`

  取得したい属性。

### 戻り値

属性の値を返します。

# mysqli_stmt::attr_set

# mysqli_stmt_attr_set

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::attr_set -- mysqli_stmt_attr_set — プリペアドステートメントの振る舞いを変更する

### 説明

オブジェクト指向型

public function mysqli_stmt::attr_set(int `$attribute`, int `$value`): bool

手続き型

function 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 です。 PHP 8.4.0 で削除されました。

  `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::bind_param

# mysqli_stmt_bind_param

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::bind_param -- mysqli_stmt_bind_param — プリペアドステートメントのパラメータに変数をバインドする

### 説明

オブジェクト指向型

public function mysqli_stmt::bind_param(string `$types`, mixed `&$var`, mixed `&...$vars`): bool

手続き型

function 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_result

# mysqli_stmt_bind_result

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::bind_result -- mysqli_stmt_bind_result — 結果を保存するため、プリペアドステートメントに変数をバインドする

### 説明

オブジェクト指向型

public function mysqli_stmt::bind_result(mixed `&$var`, mixed `&...$vars`): bool

手続き型

function 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::close

# mysqli_stmt_close

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::close -- mysqli_stmt_close — プリペアドステートメントを閉じる

### 説明

オブジェクト指向型

public function mysqli_stmt::close(): true

手続き型

function 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::__construct

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::__construct — 新しい mysqli_stmt オブジェクトを構築する

### 説明

public function 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::data_seek

# mysqli_stmt_data_seek

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::data_seek -- mysqli_stmt_data_seek — バッファリングされた結果中の、任意の行にポインタを移動する

### 説明

オブジェクト指向型

public function mysqli_stmt::data_seek(int `$offset`): void

手続き型

function 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::$errno

# mysqli_stmt_errno

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$errno -- mysqli_stmt_errno — 直近のステートメントのコールに関するエラーコードを返す

### 説明

オブジェクト指向型

int $mysqli_stmt->errno;

手続き型

function 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::$error

# mysqli_stmt_error

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$error -- mysqli_stmt_error — 直近のステートメントのエラー内容を文字列で返す

### 説明

オブジェクト指向型

string $mysqli_stmt->error;

手続き型

function 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_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;

手続き型

function 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(mysqli_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::execute

# mysqli_stmt_execute

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::execute -- mysqli_stmt_execute — プリペアドステートメントを実行する

### 説明

オブジェクト指向型

public function mysqli_stmt::execute(?array `$params` = `null`): bool

手続き型

function 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::fetch

# mysqli_stmt_fetch

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::fetch -- mysqli_stmt_fetch — プリペアドステートメントから結果を取得し、バインド変数に格納する

### 説明

オブジェクト指向型

public function mysqli_stmt::fetch(): ?bool

手続き型

function 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::$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;

手続き型

function 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::free_result

# mysqli_stmt_free_result

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::free_result -- mysqli_stmt_free_result — 指定したステートメントハンドルの結果を格納したメモリを開放する

### 説明

オブジェクト指向型

public function mysqli_stmt::free_result(): void

手続き型

function mysqli_stmt_free_result(mysqli_stmt `$statement`): void

ステートメントに関連する結果のメモリを開放します。このメモリは mysqli_stmt_store_result() によって割り当てられたものです。

### パラメータ

`stmt`
  手続き型のみ: mysqli_stmt_init() が返す mysqli_stmt オブジェクト。

### 戻り値

値を返しません。

### 参考

- mysqli_stmt_store_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 function mysqli_stmt::get_result(): mysqli_result|false

手続き型

function 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() - 内部バッファに結果を保存する

# 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 function mysqli_stmt::get_warnings(): mysqli_warning|false

手続き型

function mysqli_stmt_get_warnings(mysqli_stmt `$statement`): mysqli_warning|false
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

# 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;

手続き型

function mysqli_stmt_insert_id(mysqli_stmt `$statement`): int|string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

# 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 function mysqli_stmt::more_results(): bool

手続き型:

function 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::next_result

# mysqli_stmt_next_result

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_stmt::next_result -- mysqli_stmt_next_result — 複数クエリから、次の結果を読み込む

### 説明

オブジェクト指向型

public function mysqli_stmt::next_result(): bool

手続き型:

function 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::$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 function mysqli_stmt::num_rows(): int|string

手続き型

function 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::$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;

手続き型

function 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文 を準備する

# mysqli_stmt::prepare

# mysqli_stmt_prepare

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::prepare -- mysqli_stmt_prepare — SQL ステートメントを実行するために準備する

### 説明

オブジェクト指向型

public function mysqli_stmt::prepare(string `$query`): bool

手続き型

function 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::reset

# mysqli_stmt_reset

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::reset -- mysqli_stmt_reset — プリペアドステートメントをリセットする

### 説明

オブジェクト指向型

public function mysqli_stmt::reset(): bool

手続き型

function 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::result_metadata

# mysqli_stmt_result_metadata

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::result_metadata -- mysqli_stmt_result_metadata — プリペアドステートメントから結果セットのメタデータを返す

### 説明

オブジェクト指向型

public function mysqli_stmt::result_metadata(): mysqli_result|false

手続き型

function mysqli_stmt_result_metadata(mysqli_stmt `$statement`): mysqli_result|false

mysqli_prepare() に渡したステートメントが 結果セットを返すものであった場合、 mysqli_stmt_result_metadata() はオブジェクトを返します。このオブジェクトは、結果のフィールド数や 各フィールドの情報などのメタ情報を取得するために使用可能です。

この関数は空の mysqli_result オブジェクトを返します。 これにより、実際のデータ行を取得せずに、 プリペアドステートメントからメタデータ情報にアクセスできます。 mysqli_stmt_get_result() を使用して、 プリペアドステートメントから結果オブジェクトとして結果セット全体を取得する場合、 この関数を使用する必要はありません。

> 注意:

> この結果セットは、 結果セットのメタデータをフィールドベースで処理する関数にのみ渡せます。 渡せる関数の例として、以下が挙げられます:

> - 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_stmt_result_metadata() が返す結果セットには メタデータのみが含まれています。実際の行データは含まれません。 行データを取得するには、ステートメントハンドルを mysqli_stmt_get_result() または、 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);
    ?>

例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_prepare() - 実行するための SQL文 を準備する
- mysqli_free_result() - 結果に関連付けられたメモリを開放する
- mysqli_stmt_get_result() - プリペアドステートメントから結果を mysqli_result オブジェクトとして取得する

# 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 function mysqli_stmt::send_long_data(int `$param_num`, string `$data`): bool

手続き型

function 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() - プリペアドステートメントのパラメータに変数をバインドする

# mysqli_stmt::$sqlstate

# mysqli_stmt_sqlstate

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::$sqlstate -- mysqli_stmt_sqlstate — 直前のステートメントの操作での SQLSTATE エラーを返す

### 説明

オブジェクト指向型

string $mysqli_stmt->sqlstate;

手続き型

function 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::store_result

# mysqli_stmt_store_result

(PHP 5, PHP 7, PHP 8)

mysqli_stmt::store_result -- mysqli_stmt_store_result — 内部バッファに結果を保存する

### 説明

オブジェクト指向型

public function mysqli_stmt::store_result(): bool

手続き型

function 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_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 クラス

(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 function __construct(mysqli `$mysql`, int `$result_mode` = `MYSQLI_STORE_RESULT`)
public function data_seek(int `$offset`): bool
public function fetch_all(int `$mode` = `MYSQLI_NUM`): array
public function fetch_array(int `$mode` = `MYSQLI_BOTH`): array|null|false
public function fetch_assoc(): array|null|false
public function fetch_column(int `$column` = 0): null|int|float|string|false
public function fetch_field(): object|false
public function fetch_field_direct(int `$index`): object|false
public function fetch_fields(): array
public function fetch_object(string `$class` = "stdClass", array `$constructor_args` = []): object|null|false
public function fetch_row(): array|null|false
public function field_seek(int `$index`): true
public function free(): void
public function close(): void
public function free_result(): void
public function getIterator(): Iterator
}

## プロパティ

type

  結果セットをバッファリングするか、しないかを整数で設定します。 (バッファリングする場合は `MYSQLI_STORE_RESULT` を、 しない場合は `MYSQLI_USE_RESULT` を それぞれ設定します)

## 変更履歴

バージョン | 説明
--- | ---
8.0.0 | mysqli_result は、 IteratorAggregate を実装するようになりました。 これより前のバージョンでは、 Traversable を実装していました。

# mysqli_result::__construct

(PHP 5, PHP 7, PHP 8)

mysqli_result::__construct — mysqli_result オブジェクトを構築する

### 説明

public function 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::$current_field

# mysqli_field_tell

(PHP 5, PHP 7, PHP 8)

mysqli_result::$current_field -- mysqli_field_tell — 結果ポインタにおける現在のフィールドオフセットを取得する

### 説明

オブジェクト指向型

int $mysqli_result->current_field;

手続き型

function 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::data_seek

# mysqli_data_seek

(PHP 5, PHP 7, PHP 8)

mysqli_result::data_seek -- mysqli_data_seek — 結果の任意の行にポインタを移動する

### 説明

オブジェクト指向型

public function mysqli_result::data_seek(int `$offset`): bool

手続き型

function 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::fetch_all

# mysqli_fetch_all

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_result::fetch_all -- mysqli_fetch_all — 結果のすべての行を連想配列・数値添字配列あるいはその両方の形式で取得する

### 説明

オブジェクト指向型

public function mysqli_result::fetch_all(int `$mode` = `MYSQLI_NUM`): array

手続き型

function 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_array

# mysqli_fetch_array

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_array -- mysqli_fetch_array — 結果セットの次の行を連想配列・数値添字配列あるいはその両方の形式で取得する

### 説明

オブジェクト指向型

public function mysqli_result::fetch_array(int `$mode` = `MYSQLI_BOTH`): array|null|false

手続き型

function 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_assoc

# mysqli_fetch_assoc

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_assoc -- mysqli_fetch_assoc — 結果セットの次の行を連想配列で取得する

### 説明

オブジェクト指向型

public function mysqli_result::fetch_assoc(): array|null|false

手続き型

function 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_column

# mysqli_fetch_column

(PHP 8 >= 8.1.0)

mysqli_result::fetch_column -- mysqli_fetch_column — 結果セットの次の行から、単一のカラムの値を取得する

### 説明

オブジェクト指向型

public function mysqli_result::fetch_column(int `$column` = 0): null|int|float|string|false

手続き型

function 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_field

# mysqli_fetch_field

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_field -- mysqli_fetch_field — 結果セットの次のフィールドを返す

### 説明

オブジェクト指向型

public function mysqli_result::fetch_field(): object|false

手続き型

function 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_direct

# mysqli_fetch_field_direct

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_field_direct -- mysqli_fetch_field_direct — 単一のフィールドのメタデータを取得する

### 説明

オブジェクト指向型

public function mysqli_result::fetch_field_direct(int `$index`): object|false

手続き型

function 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_fields

# mysqli_fetch_fields

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_fields -- mysqli_fetch_fields — 結果セットのフィールド情報をオブジェクトの配列で返す

### 説明

オブジェクト指向型

public function mysqli_result::fetch_fields(): array

手続き型

function 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_object

# mysqli_fetch_object

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_object -- mysqli_fetch_object — 結果セットの次の行を取得し、オブジェクトとして返す

### 説明

オブジェクト指向型

public function mysqli_result::fetch_object(string `$class` = "stdClass", array `$constructor_args` = []): object|null|false

手続き型

function 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_row

# mysqli_fetch_row

(PHP 5, PHP 7, PHP 8)

mysqli_result::fetch_row -- mysqli_fetch_row — 結果セットの次の行を数値添字配列で取得する

### 説明

オブジェクト指向型

public function mysqli_result::fetch_row(): array|null|false

手続き型

function 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::$field_count

# mysqli_num_fields

(PHP 5, PHP 7, PHP 8)

mysqli_result::$field_count -- mysqli_num_fields — 結果セットのフィールド数を取得する

### 説明

オブジェクト指向型

int $mysqli_result->field_count;

手続き型

function 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_seek

# mysqli_field_seek

(PHP 5, PHP 7, PHP 8)

mysqli_result::field_seek -- mysqli_field_seek — 結果ポインタを、指定したフィールドオフセットに設定する

### 説明

オブジェクト指向型

public function mysqli_result::field_seek(int `$index`): true

手続き型

function 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::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 function mysqli_result::free(): void
public function mysqli_result::close(): void
public function mysqli_result::free_result(): void

手続き型

function 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::getIterator

(PHP 8)

mysqli_result::getIterator — 外部イテレータを取得する

### 説明

public function mysqli_result::getIterator(): Iterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# mysqli_result::$lengths

# mysqli_fetch_lengths

(PHP 5, PHP 7, PHP 8)

mysqli_result::$lengths -- mysqli_fetch_lengths — 結果セットにおける現在の行のカラムの長さを返す

### 説明

オブジェクト指向型

?array $mysqli_result->lengths;

手続き型

function 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::$num_rows

# mysqli_num_rows

(PHP 5, PHP 7, PHP 8)

mysqli_result::$num_rows -- mysqli_num_rows — 結果セットの行数を取得する

### 説明

オブジェクト指向型

int|string $mysqli_result->num_rows;

手続き型

function 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_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 クラス

(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_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 function mysqli_driver::embedded_server_end(): void

手続き型

function mysqli_embedded_server_end(): void
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

# 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 function mysqli_driver::embedded_server_start(int `$start`, array `$arguments`, array `$groups`): bool

手続き型

function mysqli_embedded_server_start(int `$start`, array `$arguments`, array `$groups`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

# mysqli_driver::$report_mode

# mysqli_report

(PHP 5, PHP 7, PHP 8)

mysqli_driver::$report_mode -- mysqli_report — mysqli のエラー報告モードを設定する

### 説明

オブジェクト指向型

int $mysqli_driver->report_mode;

手続き型

function mysqli_report(int `$flags`): true

フラグに応じて、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_driver::embedded_server_end — 組み込みサーバーを停止する
- mysqli_driver::embedded_server_start — 組み込みサーバーを初期化して開始する
- mysqli_driver::$report_mode — mysqli のエラー報告モードを設定する

# mysqli_warning クラス

(PHP 5, PHP 7, PHP 8)

## はじめに

MySQL の警告を表します。

## クラス概要

final class mysqli_warning {
/* プロパティ */
public string $message;
public string $sqlstate;
public int $errno;
/* メソッド */
private function __construct()
public function next(): bool
}

## プロパティ

message

  メッセージ文字列

sqlstate

  SQL state

errno

  エラー番号

# mysqli_warning::__construct

(PHP 5, PHP 7, PHP 8)

mysqli_warning::__construct — インスタンス化を禁止するための private なコンストラクタ

### 説明

private function mysqli_warning::__construct()

### パラメータ

この関数にはパラメータはありません。

# mysqli_warning::next

(PHP 5, PHP 7, PHP 8)

mysqli_warning::next — 次の警告を取得する

### 説明

public function mysqli_warning::next(): bool

可能であれば、次の警告の情報を変更します。

次の警告に情報が送信されると、 mysqli_warning の 新しいプロパティ `message`, `sqlstate` および `errno` の値が利用可能になります。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

次の警告の取得に成功すれば `true` を返します。 警告がない場合は、`false` を返します。

## 目次

- mysqli_warning::__construct — インスタンス化を禁止するための private なコンストラクタ
- mysqli_warning::next — 次の警告を取得する

# 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 function getSqlState(): string
/* 継承したメソッド */
public function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

## プロパティ

sqlstate

  エラーの SQLSTATE。

# mysqli_sql_exception::getSqlState

(PHP 8 >= 8.1.2)

mysqli_sql_exception::getSqlState — SQLSTATE エラーコードを含む情報を返す

### 説明

public function 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_sql_exception::getSqlState — SQLSTATE エラーコードを含む情報を返す

# エイリアスおよび非推奨の Mysqli 関数

# mysqli_connect

(PHP 5, PHP 7, PHP 8)

mysqli_connect — mysqli::__construct() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 mysqli::__construct()

> 注意:

> mysqli の例外モードが無効な場合、かつ接続に失敗した場合、 mysqli_connect() 関数はオブジェクトではなく `false` を返します。 接続エラーの内容を取得するのに、 mysqli_connect_error() 関数が使えます。

# 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_execute

(PHP 5, PHP 7, PHP 8)

mysqli_execute — mysqli_stmt_execute() のエイリアス

警告

この関数は PHP 8.5.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

この関数は次の関数のエイリアスです。 mysqli_stmt_execute()

### 参考

- mysqli_stmt_execute() - プリペアドステートメントを実行する

# mysqli_get_client_stats

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mysqli_get_client_stats — プロセスごとのクライアントの統計を返す

### 説明

function 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_links_stats

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

mysqli_get_links_stats — オープン済みとキャッシュ済みのリンクに関する情報を返す

### 説明

function mysqli_get_links_stats(): array

mysqli_get_links_stats() 関数は、 オープン済みとキャッシュ済みの MySQL リンクに関する情報を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

mysqli_get_links_stats() 関数は、3つの要素からなる連想配列を返します。 キーは次のとおりです:

`total`

  オープンされているリンクの合計数を示す int

`active_plinks`

  アクティブな永続的な接続の数を示す int

`cached_plinks`

  アクティブでない永続的な接続の数を示す int

# mysqli_report

(PHP 5, PHP 7, PHP 8)

mysqli_report — mysqli_driver->report_mode のエイリアス

### 説明

この関数は次の関数のエイリアスです。 mysqli_driver->report_mode

# mysqli::set_opt

# mysqli_set_opt

(PHP 5, PHP 7, PHP 8)

mysqli::set_opt -- mysqli_set_opt — mysqli_options() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 mysqli_options()

## 目次

- 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 のエイリアス

# 変更履歴

この拡張モジュールのクラス/関数/メソッドには次のような変更がありました。

Version | Function | Description
--- | --- | ---
8.4.0 | mysqli::kill | mysqli::kill と mysqli_kill は非推奨となりました。代わりに KILL SQL コマンドを使用してください。
| mysqli::ping | mysqli::ping と mysqli_ping は非推奨となりました。 reconnect 機能は PHP 8.2.0 で廃止されたため、この関数はもはや必要ありません。
| mysqli::refresh | mysqli::refresh と mysqli_refresh は非推奨となりました。代わりに FLUSH SQL コマンドを使用してください。
| mysqli::store_result | mode パラメータの指定は非推奨となりました。 PHP 8.1 以降では、このパラメータを指定しても意味はありません。
8.3.0 | mysqli_result::fetch_object | constructor_args が空でないのに、 そのクラスがコンストラクタを持たない場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、 Exception がスローされていました。
| mysqli::poll | read と error を両方渡さなかった場合には、 ValueError がスローされるようになりました。
8.1.0 | mysqli_driver::$report_mode | デフォルト値が MYSQLI_REPORT_ERROR | MYSQLI_REPORT_STRICT になりました。 これより前のバージョンでは、 MYSQLI_REPORT_OFF でした。
| mysqli_result::fetch_all | libmysqlclient をリンクしている場合でも、 この関数を使えるようになりました。
| mysqli_stmt::execute | オプションの引数 params が追加されました。
| mysqli_stmt::next_result | libmysqlclient をリンクしている場合でも、 この関数を使えるようになりました。
| mysqli::__construct | mysqli::connect は、成功時に null ではなく true を返すようになりました。
| mysqli::$client_info | mysqli_get_client_info を 引数 mysql を付けて呼ぶことは、 推奨されなくなりました。 この関数はもはや引数を取ることはありませんが、 オプションの引数として、間違って値を渡すことは許されています。
| mysqli::$client_info | オブジェクト指向版の mysqli::get_client_info は、推奨されなくなりました。
| mysqli::init | オブジェクト指向版の mysqli::init メソッドは、 推奨されなくなりました。 parent::init を、 parent::__construct の呼び出しに置き換えて下さい。
8.0.0 | mysqli_result::fetch_object | constructor_args は、 引数を指定しない場合に [] を受け入れるようになりました。 これより前のバージョンでは、例外がスローされていました。
| mysqli_result::field_seek | この関数は、常に true を返すようになりました。 これより前のバージョンでは、失敗時に false を返していました。
| mysqli_stmt::close | この関数は、常に true を返すようになりました。 これより前のバージョンでは、失敗時に false を返していました。
| mysqli_stmt::__construct | query は、nullable になりました。
| mysqli::begin_transaction | name は、nullable になりました。
| mysqli::close | この関数は、常に true を返すようになりました。 これより前のバージョンでは、失敗時に false を返していました。
| mysqli::commit | name は、nullable になりました。
| mysqli::debug | この関数は、常に true を返すようになりました。 これより前のバージョンでは、失敗時に false を返していました。
| mysqli::rollback | name は、nullable になりました。
7.4.0 | mysqli::__construct | すべてのパラメータが、nullable になりました。
| mysqli::real_connect | すべてのパラメータが、nullable になりました。

- mysqli の概要
- クイックスタートガイド
  - 手続き型とオブジェクト指向インターフェイス
  - データベース接続
  - ステートメントの実行
  - プリペアドステートメント
  - ストアドプロシージャ
  - 複数のステートメント
  - トランザクションのサポート
  - メタデータ
- インストール/設定
  - 要件
  - インストール手順
  - 実行時設定
- mysqli 拡張モジュールでの持続的接続
- 定義済み定数
- ノート
- MySQLi 拡張モジュールの関数概要
- 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 のエイリアス
- 変更履歴

# Mysql_xdevapi

# はじめに

この拡張モジュールは、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_xdevapi\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

(No version information available, might only be in Git)

expression — プリペアドステートメントの変数をパラメータとしてバインドする

### 説明

function 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

# getSession

(No version information available, might only be in Git)

getSession — MySQL サーバーに接続する

### 説明

function 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"
    }

## 目次

- expression — プリペアドステートメントの変数をパラメータとしてバインドする
- getSession — MySQL サーバーに接続する

# BaseResult クラス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

## クラス概要

class mysql_xdevapi\BaseResult {
/* メソッド */
abstract public function getWarnings(): array
abstract public function getWarningsCount(): int
}

# BaseResult::getWarnings

(No version information available, might only be in Git)

BaseResult::getWarnings — 直近の操作の警告を取得する

### 説明

abstract public function 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::getWarningsCount

(No version information available, might only be in Git)

BaseResult::getWarningsCount — 直近の操作から発生した警告の数を取得する

### 説明

abstract public function 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

## 目次

- BaseResult::getWarnings — 直近の操作の警告を取得する
- BaseResult::getWarningsCount — 直近の操作から発生した警告の数を取得する

# クライアントクラス

(No version information available, might only be in Git)

## はじめに

コネクションプールへのアクセスを提供します。

## クラス概要

class mysql_xdevapi\Client {
/* メソッド */
public function close(): bool
public function getSession(): mysql_xdevapi\Session
}

# mysql_xdevapi\Client::close

(No version information available, might only be in Git)

mysql_xdevapi\Client::close — クライアントの接続を閉じる

### 説明

public function mysql_xdevapi\Client::close(): bool

サーバーとのクライアントの接続を全て閉じます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

接続が閉じられれば `true` を返します。

# Client::__construct

(No version information available, might only be in Git)

Client::__construct — Client のコンストラクタ

### 説明

private function 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::getClient

(No version information available, might only be in Git)

Client::getClient — クライアントのセッションを取得する

### 説明

public function mysql_xdevapi\Client::getSession(): mysql_xdevapi\Session

クライアントと関連付けられたセッションを取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

セッションオブジェクトを返します。

## 目次

- mysql_xdevapi\Client::close — クライアントの接続を閉じる
- Client::__construct — Client のコンストラクタ
- Client::getClient — クライアントのセッションを取得する

# Collection クラス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

## クラス概要

class mysql_xdevapi\Collection implements mysql_xdevapi\SchemaObject {
/* プロパティ */
public $name;
/* メソッド */
public function add(mixed `$document`): mysql_xdevapi\CollectionAdd
public function addOrReplaceOne(string `$id`, string `$doc`): mysql_xdevapi\Result
public function count(): int
public function createIndex(string `$index_name`, string `$index_desc_json`): void
public function dropIndex(string `$index_name`): bool
public function existsInDatabase(): bool
public function find(string `$search_condition` = ?): mysql_xdevapi\CollectionFind
public function getName(): string
public function getOne(string `$id`): Document
public function getSchema(): Schema Object
public function getSession(): Session
public function modify(string `$search_condition`): mysql_xdevapi\CollectionModify
public function remove(string `$search_condition`): mysql_xdevapi\CollectionRemove
public function removeOne(string `$id`): mysql_xdevapi\Result
public function replaceOne(string `$id`, string `$doc`): mysql_xdevapi\Result
}

## プロパティ

name

# Collection::add

(No version information available, might only be in Git)

Collection::add — コレクションにドキュメントを追加する

### 説明

public function 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::addOrReplaceOne

(No version information available, might only be in Git)

Collection::addOrReplaceOne — コレクションのドキュメントを追加または置換する

### 説明

public function 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::__construct

(No version information available, might only be in Git)

Collection::__construct — Collection のコンストラクタ

### 説明

private function 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::count

(No version information available, might only be in Git)

Collection::count — ドキュメントの数を取得する

### 説明

public function 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::createIndex

(No version information available, might only be in Git)

Collection::createIndex — コレクションにインデックスを作成

### 説明

public function 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::dropIndex

(No version information available, might only be in Git)

Collection::dropIndex — コレクションのインデックスを削除

### 説明

public function 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::existsInDatabase

(No version information available, might only be in Git)

Collection::existsInDatabase — コレクションがデータベースに存在するかをチェックする

### 説明

public function 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::find

(No version information available, might only be in Git)

Collection::find — ドキュメントを検索する

### 説明

public function 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::getName

(No version information available, might only be in Git)

Collection::getName — コレクションの名前を得る

### 説明

public function 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::getOne

(No version information available, might only be in Git)

Collection::getOne — ドキュメントをひとつ取得

### 説明

public function 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::getSchema

(No version information available, might only be in Git)

Collection::getSchema — スキーマオブジェクトを得る

### 説明

public function 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::getSession

(No version information available, might only be in Git)

Collection::getSession — セッションオブジェクトを取得

### 説明

public function 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::modify

(No version information available, might only be in Git)

Collection::modify — コレクションのドキュメントを変更する

### 説明

public function 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::remove

(No version information available, might only be in Git)

Collection::remove — コレクションを削除する

### 説明

public function 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::removeOne

(No version information available, might only be in Git)

Collection::removeOne — コレクションからドキュメントをひとつ削除する

### 説明

public function 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::replaceOne

(No version information available, might only be in Git)

Collection::replaceOne — コレクションのドキュメントをひとつ置き換える

### 説明

public function 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);

    ?>

## 目次

- 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 — コレクションのドキュメントをひとつ置き換える

# CollectionAdd クラス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

## クラス概要

class mysql_xdevapi\CollectionAdd implements mysql_xdevapi\Executable {
/* メソッド */
public function execute(): mysql_xdevapi\Result
}

# CollectionAdd::__construct

(No version information available, might only be in Git)

CollectionAdd::__construct — CollectionAdd のコンストラクタ

### 説明

private function 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::execute

(No version information available, might only be in Git)

CollectionAdd::execute — ステートメントを実行する

### 説明

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

## 目次

- CollectionAdd::__construct — CollectionAdd のコンストラクタ
- CollectionAdd::execute — ステートメントを実行する

# 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 function bind(array `$placeholder_values`): mysql_xdevapi\CollectionFind
public function execute(): mysql_xdevapi\DocResult
public function fields(string `$projection`): mysql_xdevapi\CollectionFind
public function groupBy(string `$sort_expr`): mysql_xdevapi\CollectionFind
public function having(string `$sort_expr`): mysql_xdevapi\CollectionFind
public function limit(int `$rows`): mysql_xdevapi\CollectionFind
public function lockExclusive(int `$lock_waiting_option` = ?): mysql_xdevapi\CollectionFind
public function lockShared(int `$lock_waiting_option` = ?): mysql_xdevapi\CollectionFind
public function offset(int `$position`): mysql_xdevapi\CollectionFind
public function sort(string `$sort_expr`): mysql_xdevapi\CollectionFind
}

# CollectionFind::bind

(No version information available, might only be in Git)

CollectionFind::bind — クエリのプレースホルダーに値をバインドする

### 説明

public function 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::__construct

(No version information available, might only be in Git)

CollectionFind::__construct — CollectionFind のコンストラクタ

### 説明

private function 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::execute

(No version information available, might only be in Git)

CollectionFind::execute — ステートメントを実行する

### 説明

public function 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::fields

(No version information available, might only be in Git)

CollectionFind::fields — ドキュメントのフィールドのフィルタを設定する

### 説明

public function 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::groupBy

(No version information available, might only be in Git)

CollectionFind::groupBy — グループ化の条件を設定する

### 説明

public function 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::having

(No version information available, might only be in Git)

CollectionFind::having — 集約関数の条件を設定する

### 説明

public function 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::limit

(No version information available, might only be in Git)

CollectionFind::limit — 返されるドキュメントの数を限定する

### 説明

public function 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"
      }
    }

# CollectionFind::lockExclusive

(No version information available, might only be in Git)

CollectionFind::lockExclusive — Execute operation with EXCLUSIVE LOCK

### 説明

public function 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();
    ?>

# CollectionFind::lockShared

(No version information available, might only be in Git)

CollectionFind::lockShared — SHARED LOCK 付きで操作を実行する

### 説明

public function 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::offset

(No version information available, might only be in Git)

CollectionFind::offset — 返される要素の数から、与えられた数をスキップする

### 説明

public function 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::sort

(No version information available, might only be in Git)

CollectionFind::sort — ソート条件を設定する

### 説明

public function 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"
      }
    }

## 目次

- 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 — ソート条件を設定する

# 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 function arrayAppend(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify
public function arrayInsert(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify
public function bind(array `$placeholder_values`): mysql_xdevapi\CollectionModify
public function execute(): mysql_xdevapi\Result
public function limit(int `$rows`): mysql_xdevapi\CollectionModify
public function patch(string `$document`): mysql_xdevapi\CollectionModify
public function replace(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify
public function set(string `$collection_field`, string `$expression_or_literal`): mysql_xdevapi\CollectionModify
public function skip(int `$position`): mysql_xdevapi\CollectionModify
public function sort(string `$sort_expr`): mysql_xdevapi\CollectionModify
public function unset(array `$fields`): mysql_xdevapi\CollectionModify
}

# CollectionModify::arrayAppend

(No version information available, might only be in Git)

CollectionModify::arrayAppend — 配列のフィールドに要素を追加する

### 説明

public function 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::arrayInsert

(No version information available, might only be in Git)

CollectionModify::arrayInsert — 配列のフィールドに要素を挿入する

### 説明

public function 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::bind

(No version information available, might only be in Git)

CollectionModify::bind — クエリのプレースホルダーに値をバインドする

### 説明

public function 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::__construct

(No version information available, might only be in Git)

CollectionModify::__construct — CollectionModify のコンストラクタ

### 説明

private function 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::execute

(No version information available, might only be in Git)

CollectionModify::execute — 変更の操作を実行する

### 説明

public function mysql_xdevapi\CollectionModify::execute(): mysql_xdevapi\Result

MySQLサーバーに CRUD 操作のリクエストを送信するために、 execute メソッドは必須です。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

影響を受けた行数のような、操作の状態を確認するために使われる Result オブジェクトを返します。

### 例

例1 mysql_xdevapi\CollectionModify::execute() の例

    <?php

    /* ... */

    ?>

# CollectionModify::limit

(No version information available, might only be in Git)

CollectionModify::limit — 変更されるドキュメントの数を限定する

### 説明

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

# CollectionModify::patch

(No version information available, might only be in Git)

CollectionModify::patch — document にパッチを当てる

### 説明

public function 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::replace

(No version information available, might only be in Git)

CollectionModify::replace — ドキュメントのフィールドを置き換える

### 説明

public function 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::set

(No version information available, might only be in Git)

CollectionModify::set — ドキュメントの属性を設定する

### 説明

public function 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::skip

(No version information available, might only be in Git)

CollectionModify::skip — 要素をスキップする

### 説明

public function 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::sort

(No version information available, might only be in Git)

CollectionModify::sort — ソート条件を設定する

### 説明

public function 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::unset

(No version information available, might only be in Git)

CollectionModify::unset — ドキュメントのフィールドの値を削除する

### 説明

public function 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();

    ?>

## 目次

- 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 — ドキュメントのフィールドの値を削除する

# 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 function bind(array `$placeholder_values`): mysql_xdevapi\CollectionRemove
public function execute(): mysql_xdevapi\Result
public function limit(int `$rows`): mysql_xdevapi\CollectionRemove
public function sort(string `$sort_expr`): mysql_xdevapi\CollectionRemove
}

# CollectionRemove::bind

(No version information available, might only be in Git)

CollectionRemove::bind — プレースホルダーに値をバインドする

### 説明

public function 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::__construct

(No version information available, might only be in Git)

CollectionRemove::__construct — CollectionRemove のコンストラクタ

### 説明

private function 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::execute

(No version information available, might only be in Git)

CollectionRemove::execute — 削除操作を実行する

### 説明

public function 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::limit

(No version information available, might only be in Git)

CollectionRemove::limit — 削除するドキュメントの数を限定する

### 説明

public function 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::sort

(No version information available, might only be in Git)

CollectionRemove::sort — ソート条件を設定する

### 説明

public function 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();

    ?>

## 目次

- CollectionRemove::bind — プレースホルダーに値をバインドする
- CollectionRemove::__construct — CollectionRemove のコンストラクタ
- CollectionRemove::execute — 削除操作を実行する
- CollectionRemove::limit — 削除するドキュメントの数を限定する
- CollectionRemove::sort — ソート条件を設定する

# ColumnResult クラス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

## クラス概要

class mysql_xdevapi\ColumnResult {
/* メソッド */
public function getCharacterSetName(): string
public function getCollationName(): string
public function getColumnLabel(): string
public function getColumnName(): string
public function getFractionalDigits(): int
public function getLength(): int
public function getSchemaName(): string
public function getTableLabel(): string
public function getTableName(): string
public function getType(): int
public function isNumberSigned(): int
public function isPadded(): int
}

# ColumnResult::__construct

(No version information available, might only be in Git)

ColumnResult::__construct — ColumnResult のコンストラクタ

### 説明

private function 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::getCharacterSetName

(No version information available, might only be in Git)

ColumnResult::getCharacterSetName — キャラクタセットを取得する

### 説明

public function mysql_xdevapi\ColumnResult::getCharacterSetName(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

### 例

例1 mysql_xdevapi\ColumnResult::getCharacterSetName() の例

    <?php

    /* ... */

    ?>

# ColumnResult::getCollationName

(No version information available, might only be in Git)

ColumnResult::getCollationName — 照合順序名を取得する

### 説明

public function mysql_xdevapi\ColumnResult::getCollationName(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

### 例

例1 mysql_xdevapi\ColumnResult::getCollationName() の例

    <?php

    /* ... */

    ?>

# ColumnResult::getColumnLabel

(No version information available, might only be in Git)

ColumnResult::getColumnLabel — カラムのラベルを取得する

### 説明

public function mysql_xdevapi\ColumnResult::getColumnLabel(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

### 例

例1 mysql_xdevapi\ColumnResult::getColumnLabel() の例

    <?php

    /* ... */

    ?>

# ColumnResult::getColumnName

(No version information available, might only be in Git)

ColumnResult::getColumnName — カラム名を取得する

### 説明

public function mysql_xdevapi\ColumnResult::getColumnName(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

### 例

例1 mysql_xdevapi\ColumnResult::getColumnName() の例

    <?php

    /* ... */

    ?>

# ColumnResult::getFractionalDigits

(No version information available, might only be in Git)

ColumnResult::getFractionalDigits — カラムの小数の桁数を取得する

### 説明

public function mysql_xdevapi\ColumnResult::getFractionalDigits(): int

カラムの小数の桁数を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

### 例

例1 mysql_xdevapi\ColumnResult::getFractionalDigits() の例

    <?php

    /* ... */

    ?>

# ColumnResult::getLength

(No version information available, might only be in Git)

ColumnResult::getLength — カラムのフィールドの長さを取得する

### 説明

public function mysql_xdevapi\ColumnResult::getLength(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

### 例

例1 mysql_xdevapi\ColumnResult::getLength() の例

    <?php

    /* ... */

    ?>

# ColumnResult::getSchemaName

(No version information available, might only be in Git)

ColumnResult::getSchemaName — スキーマ名を取得する

### 説明

public function mysql_xdevapi\ColumnResult::getSchemaName(): string

カラムが保存されているスキーマの名前を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

### 例

例1 mysql_xdevapi\ColumnResult::getSchemaName() の例

    <?php

    /* ... */

    ?>

# ColumnResult::getTableLabel

(No version information available, might only be in Git)

ColumnResult::getTableLabel — テーブルラベルを取得する

### 説明

public function mysql_xdevapi\ColumnResult::getTableLabel(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

### 例

例1 mysql_xdevapi\ColumnResult::getTableLabel() の例

    <?php

    /* ... */

    ?>

# ColumnResult::getTableName

(No version information available, might only be in Git)

ColumnResult::getTableName — テーブル名を取得する

### 説明

public function mysql_xdevapi\ColumnResult::getTableName(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

オブジェクトに対応するテーブル名を返します。

### 例

例1 mysql_xdevapi\ColumnResult::getTableName() の例

    <?php

    /* ... */

    ?>

# ColumnResult::getType

(No version information available, might only be in Git)

ColumnResult::getType — カラムの型を取得する

### 説明

public function mysql_xdevapi\ColumnResult::getType(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

### 例

例1 mysql_xdevapi\ColumnResult::getType() の例

    <?php

    /* ... */

    ?>

# ColumnResult::isNumberSigned

(No version information available, might only be in Git)

ColumnResult::isNumberSigned — 符号付きの型かどうかを調べる

### 説明

public function mysql_xdevapi\ColumnResult::isNumberSigned(): int

テーブルのカラム情報を取得します。 mysql_xdevapi\RowResult::getColumns() によってインスタンス化されます。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

与えられたカラムが符号付きの場合、`true` を返します。

### 例

例1 mysql_xdevapi\ColumnResult::isNumberSigned() の例

    <?php

    /* ... */

    ?>

# ColumnResult::isPadded

(No version information available, might only be in Git)

ColumnResult::isPadded — パディングされているかを調べる

### 説明

public function mysql_xdevapi\ColumnResult::isPadded(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

与えられたカラムがパディングされていれば `true` を返します。

### 例

例1 mysql_xdevapi\ColumnResult::isPadded() の例

    <?php

    /* ... */

    ?>

## 目次

- 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 — パディングされているかを調べる

# CrudOperationBindable インターフェイス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

## クラス概要

class mysql_xdevapi\CrudOperationBindable {
/* メソッド */
abstract public function bind(array `$placeholder_values`): mysql_xdevapi\CrudOperationBindable
}

# CrudOperationBindable::bind

(No version information available, might only be in Git)

CrudOperationBindable::bind — プレースホルダーに値をバインドする

### 説明

abstract public function 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();

    ?>

## 目次

- CrudOperationBindable::bind — プレースホルダーに値をバインドする

# CrudOperationLimitable インターフェイス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

## クラス概要

class mysql_xdevapi\CrudOperationLimitable {
/* メソッド */
abstract public function limit(int `$rows`): mysql_xdevapi\CrudOperationLimitable
}

# CrudOperationLimitable::limit

(No version information available, might only be in Git)

CrudOperationLimitable::limit — 結果を限定する

### 説明

abstract public function 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();

    ?>

## 目次

- CrudOperationLimitable::limit — 結果を限定する

# CrudOperationSkippable インターフェイス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

## クラス概要

class mysql_xdevapi\CrudOperationSkippable {
/* メソッド */
abstract public function skip(int `$skip`): mysql_xdevapi\CrudOperationSkippable
}

# CrudOperationSkippable::skip

(No version information available, might only be in Git)

CrudOperationSkippable::skip — スキップする操作の数

### 説明

abstract public function 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();

    ?>

## 目次

- CrudOperationSkippable::skip — スキップする操作の数

# CrudOperationSortable インターフェイス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

## クラス概要

class mysql_xdevapi\CrudOperationSortable {
/* メソッド */
abstract public function sort(string `$sort_expr`): mysql_xdevapi\CrudOperationSortable
}

# CrudOperationSortable::sort

(No version information available, might only be in Git)

CrudOperationSortable::sort — 結果をソートする

### 説明

abstract public function 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();

    ?>

## 目次

- CrudOperationSortable::sort — 結果をソートする

# DatabaseObject インターフェイス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

## クラス概要

class mysql_xdevapi\DatabaseObject {
/* メソッド */
abstract public function existsInDatabase(): bool
abstract public function getName(): string
abstract public function getSession(): mysql_xdevapi\Session
}

# DatabaseObject::existsInDatabase

(No version information available, might only be in Git)

DatabaseObject::existsInDatabase — オブジェクトがデータベースに存在するかをチェックする

### 説明

abstract public function mysql_xdevapi\DatabaseObject::existsInDatabase(): bool

データベースオブジェクトが、データベース内に存在するオブジェクトを参照しているかを調べます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

オブジェクトがデータベースに存在していれば `true` を返します。 そうでなければ、`false` を返します。

### 例

例1 mysql_xdevapi\DatabaseObject::existsInDatabase() の例

    <?php

    $existInDb = $dbObj->existsInDatabase();

    ?>

# DatabaseObject::getName

(No version information available, might only be in Git)

DatabaseObject::getName — オブジェクトの名前を取得する

### 説明

abstract public function mysql_xdevapi\DatabaseObject::getName(): string

このデータベースオブジェクトの名前を取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

データベースオブジェクトの名前を返します。

### 例

例1 mysql_xdevapi\DatabaseObject::getName() の例

    <?php

    $dbObjName = $dbObj->getName();

    ?>

# DatabaseObject::getSession

(No version information available, might only be in Git)

DatabaseObject::getSession — セッションの名前を取得する

### 説明

abstract public function mysql_xdevapi\DatabaseObject::getSession(): mysql_xdevapi\Session

データベースオブジェクトに紐付いたセッションを取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Session オブジェクトを返します。

### 例

例1 mysql_xdevapi\DatabaseObject::getSession() の例

    <?php

    $session = $dbObj->getSession();

    ?>

## 目次

- DatabaseObject::existsInDatabase — オブジェクトがデータベースに存在するかをチェックする
- DatabaseObject::getName — オブジェクトの名前を取得する
- DatabaseObject::getSession — セッションの名前を取得する

# DocResult クラス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

## クラス概要

class mysql_xdevapi\DocResult implements mysql_xdevapi\BaseResult, Traversable {
/* メソッド */
public function fetchAll(): array
public function fetchOne(): array
public function getWarnings(): Array
public function getWarningsCount(): int
}

# DocResult::__construct

(No version information available, might only be in Git)

DocResult::__construct — DocResult のコンストラクタ

### 説明

private function 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::fetchAll

(No version information available, might only be in Git)

DocResult::fetchAll — 全ての行を取得する

### 説明

public function 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::fetchOne

(No version information available, might only be in Git)

DocResult::fetchOne — 一行取得する

### 説明

public function 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::getWarnings

(No version information available, might only be in Git)

DocResult::getWarnings — 直近の操作から発生した警告を取得する

### 説明

public function 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::getWarningsCount

(No version information available, might only be in Git)

DocResult::getWarningsCount — 直近の操作で発生した警告の数を取得する

### 説明

public function 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"
    }

## 目次

- DocResult::__construct — DocResult のコンストラクタ
- DocResult::fetchAll — 全ての行を取得する
- DocResult::fetchOne — 一行取得する
- DocResult::getWarnings — 直近の操作から発生した警告を取得する
- DocResult::getWarningsCount — 直近の操作で発生した警告の数を取得する

# 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 function execute(): mysql_xdevapi\Result
}

# Executable::execute

(No version information available, might only be in Git)

Executable::execute — ステートメントを実行する

### 説明

abstract public function 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) {
    }

## 目次

- Executable::execute — ステートメントを実行する

# ExecutionStatus クラス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

## クラス概要

class mysql_xdevapi\ExecutionStatus {
/* プロパティ */
public $affectedItems;
public $matchedItems;
public $foundItems;
public $lastInsertId;
public $lastDocumentId;
/* Constructor */
private function __construct()
}

## プロパティ

affectedItems

matchedItems

foundItems

lastInsertId

lastDocumentId

# ExecutionStatus::__construct

(No version information available, might only be in Git)

ExecutionStatus::__construct — ExecutionStatus のコンストラクタ

### 説明

private function mysql_xdevapi\ExecutionStatus::__construct()

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 例

例1 mysql_xdevapi\ExecutionStatus::__construct() の例

    <?php

    /* ... */

    ?>

## 目次

- ExecutionStatus::__construct — ExecutionStatus のコンストラクタ

# Expression クラス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

## クラス概要

class mysql_xdevapi\Expression {
/* プロパティ */
public $name;
/* Constructor */
public function __construct(string `$expression`)
}

## プロパティ

name

# Expression::__construct

(No version information available, might only be in Git)

Expression::__construct — Expression のコンストラクタ

### 説明

public function mysql_xdevapi\Expression::__construct(string `$expression`)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`expression`

### 例

例1 mysql_xdevapi\Expression::__construct() の例

    <?php

    /* ... */

    ?>

## 目次

- Expression::__construct — Expression のコンストラクタ

# Result クラス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

## クラス概要

class mysql_xdevapi\Result implements mysql_xdevapi\BaseResult, Traversable {
/* メソッド */
public function getAffectedItemsCount(): int
public function getAutoIncrementValue(): int
public function getGeneratedIds(): array
public function getWarnings(): array
public function getWarningsCount(): int
}

# Result::__construct

(No version information available, might only be in Git)

Result::__construct — Result のコンストラクタ

### 説明

private function 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::getAffectedItemsCount

(No version information available, might only be in Git)

Result::getAffectedItemsCount — 影響を受けた行数を得る

### 説明

public function 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::getAutoIncrementValue

(No version information available, might only be in Git)

Result::getAutoIncrementValue — 自動インクリメントされた値を取得する

### 説明

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

# Result::getGeneratedIds

(No version information available, might only be in Git)

Result::getGeneratedIds — 生成された id を取得する

### 説明

public function 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::getWarnings

(No version information available, might only be in Git)

Result::getWarnings — 直近の操作から発生した警告を取得する

### 説明

public function 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::getWarningsCount

(No version information available, might only be in Git)

Result::getWarningsCount — 直近の操作から生じた警告の数を取得する

### 説明

public function 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

## 目次

- Result::__construct — Result のコンストラクタ
- Result::getAffectedItemsCount — 影響を受けた行数を得る
- Result::getAutoIncrementValue — 自動インクリメントされた値を取得する
- Result::getGeneratedIds — 生成された id を取得する
- Result::getWarnings — 直近の操作から発生した警告を取得する
- Result::getWarningsCount — 直近の操作から生じた警告の数を取得する

# RowResult クラス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

## クラス概要

class mysql_xdevapi\RowResult implements mysql_xdevapi\BaseResult, Traversable {
/* メソッド */
public function fetchAll(): array
public function fetchOne(): array
public function getColumnsCount(): int
public function getColumnNames(): array
public function getColumns(): array
public function getWarnings(): array
public function getWarningsCount(): int
}

# RowResult::__construct

(No version information available, might only be in Git)

RowResult::__construct — RowResult のコンストラクタ

### 説明

private function 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::fetchAll

(No version information available, might only be in Git)

RowResult::fetchAll — 結果セットから全ての行を取得する

### 説明

public function 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::fetchOne

(No version information available, might only be in Git)

RowResult::fetchOne — 結果セットから行を取得する

### 説明

public function 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::getColumnsCount

(No version information available, might only be in Git)

RowResult::getColumnsCount — カラムの数を取得する

### 説明

public function 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::getColumnNames

(No version information available, might only be in Git)

RowResult::getColumnNames — 全てのカラム名を取得する

### 説明

public function 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::getColumns

(No version information available, might only be in Git)

RowResult::getColumns — カラムのメタデータを取得する

### 説明

public function 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::getWarnings

(No version information available, might only be in Git)

RowResult::getWarnings — 直近の操作から生じた警告を取得する

### 説明

public function 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::getWarningsCount

(No version information available, might only be in Git)

RowResult::getWarningsCount — 直近の操作から生じた警告の数を取得する

### 説明

public function 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

## 目次

- RowResult::__construct — RowResult のコンストラクタ
- RowResult::fetchAll — 結果セットから全ての行を取得する
- RowResult::fetchOne — 結果セットから行を取得する
- RowResult::getColumnsCount — カラムの数を取得する
- RowResult::getColumnNames — 全てのカラム名を取得する
- RowResult::getColumns — カラムのメタデータを取得する
- RowResult::getWarnings — 直近の操作から生じた警告を取得する
- RowResult::getWarningsCount — 直近の操作から生じた警告の数を取得する

# Schema クラス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

## クラス概要

class mysql_xdevapi\Schema implements mysql_xdevapi\DatabaseObject {
/* プロパティ */
public $name;
/* メソッド */
public function createCollection(string `$name`): mysql_xdevapi\Collection
public function dropCollection(string `$collection_name`): bool
public function existsInDatabase(): bool
public function getCollection(string `$name`): mysql_xdevapi\Collection
public function getCollectionAsTable(string `$name`): mysql_xdevapi\Table
public function getCollections(): array
public function getName(): string
public function getSession(): mysql_xdevapi\Session
public function getTable(string `$name`): mysql_xdevapi\Table
public function getTables(): array
}

## プロパティ

name

# Schema::__construct

(No version information available, might only be in Git)

Schema::__construct — Schema のコンストラクタ

### 説明

private function 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::createCollection

(No version information available, might only be in Git)

Schema::createCollection — スキーマにコレクションを追加する

### 説明

public function 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::dropCollection

(No version information available, might only be in Git)

Schema::dropCollection — スキーマからコレクションを削除する

### 説明

public function 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::existsInDatabase

(No version information available, might only be in Git)

Schema::existsInDatabase — データベースに存在するかをチェックする

### 説明

public function 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::getCollection

(No version information available, might only be in Git)

Schema::getCollection — スキーマからコレクションを取得する

### 説明

public function 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::getCollectionAsTable

(No version information available, might only be in Git)

Schema::getCollectionAsTable — コレクションをテーブルオブジェクトとして取得する

### 説明

public function 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::getCollections

(No version information available, might only be in Git)

Schema::getCollections — スキーマに属する全てのコレクションを取得する

### 説明

public function 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::getName

(No version information available, might only be in Git)

Schema::getName — スキーマの名前を取得する

### 説明

public function 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::getSession

(No version information available, might only be in Git)

Schema::getSession — スキーマのセッションを取得する

### 説明

public function 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::getTable

(No version information available, might only be in Git)

Schema::getTable — スキーマのテーブルを取得する

### 説明

public function 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::getTables

(No version information available, might only be in Git)

Schema::getTables — スキーマのテーブルを取得する

### 説明

public function 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"
      }
    }

## 目次

- Schema::__construct — Schema のコンストラクタ
- Schema::createCollection — スキーマにコレクションを追加する
- Schema::dropCollection — スキーマからコレクションを削除する
- Schema::existsInDatabase — データベースに存在するかをチェックする
- Schema::getCollection — スキーマからコレクションを取得する
- Schema::getCollectionAsTable — コレクションをテーブルオブジェクトとして取得する
- Schema::getCollections — スキーマに属する全てのコレクションを取得する
- Schema::getName — スキーマの名前を取得する
- Schema::getSession — スキーマのセッションを取得する
- Schema::getTable — スキーマのテーブルを取得する
- Schema::getTables — スキーマのテーブルを取得する

# SchemaObject インターフェイス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

## クラス概要

class mysql_xdevapi\SchemaObject implements mysql_xdevapi\DatabaseObject {
/* メソッド */
abstract function getSchema(): mysql_xdevapi\Schema
}

# SchemaObject::getSchema

(No version information available, might only be in Git)

SchemaObject::getSchema — スキーマオブジェクトを得る

### 説明

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

## 目次

- SchemaObject::getSchema — スキーマオブジェクトを得る

# Session クラス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

## クラス概要

class mysql_xdevapi\Session {
/* メソッド */
public function close(): bool
public function commit(): Object
public function createSchema(string `$schema_name`): mysql_xdevapi\Schema
public function dropSchema(string `$schema_name`): bool
public function generateUUID(): string
public function getDefaultSchema(): ?mysql_xdevapi\Schema
public function getSchema(string `$schema_name`): mysql_xdevapi\Schema
public function getSchemas(): array
public function getServerVersion(): int
public function listClients(): array
public function quoteName(string `$name`): string
public function releaseSavepoint(string `$name`): void
public function rollback(): void
public function rollbackTo(string `$name`): void
public function setSavepoint(string `$name` = ?): string
public function sql(string `$query`): mysql_xdevapi\SqlStatement
public function startTransaction(): void
}

# Session::close

(No version information available, might only be in Git)

Session::close — セッションを閉じる

### 説明

public function 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::commit

(PHP 4 >= 4.4.0, PHP 5, PHP 7, PHP 8)

Session::commit — トランザクションをコミットする

### 説明

public function 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::__construct

(No version information available, might only be in Git)

Session::__construct — Session のコンストラクタ

### 説明

private function mysql_xdevapi\Session::__construct()

セッションオブジェクトです。 getSession() によってインスタンス化されます。

### パラメータ

この関数にはパラメータはありません。

### 例

例1 mysql_xdevapi\Session::__construct() の例

    <?php
    $session = mysql_xdevapi\getSession("mysqlx://user:password@localhost");
    $session->close();
    ?>

# Session::createSchema

(No version information available, might only be in Git)

Session::createSchema — 新しいスキーマを作成する

### 説明

public function 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::dropSchema

(No version information available, might only be in Git)

Session::dropSchema — スキーマを削除します

### 説明

public function 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();
    ?>

# Session::generateUUID

(No version information available, might only be in Git)

Session::generateUUID — 新しいUUIDを取得する

### 説明

public function 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::getDefaultSchema

(No version information available, might only be in Git)

Session::getDefaultSchema — デフォルトのスキーマ名を取得する

### 説明

public function mysql_xdevapi\Session::getDefaultSchema(): ?mysql_xdevapi\Schema

通常接続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->getName();
    ?>

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

    testx

# Session::getSchema

(No version information available, might only be in Git)

Session::getSchema — 新しいスキーマオブジェクトを取得する

### 説明

public function 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::getSchemas

(No version information available, might only be in Git)

Session::getSchemas — スキーマを取得する

### 説明

public function 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::getServerVersion

(No version information available, might only be in Git)

Session::getServerVersion — サーバーのバージョンを取得する

### 説明

public function 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::listClients

(No version information available, might only be in Git)

Session::listClients — クライアントの一覧を取得する

### 説明

public function 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::quoteName

(No version information available, might only be in Git)

Session::quoteName — クォートを追加する

### 説明

public function 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::releaseSavepoint

(No version information available, might only be in Git)

Session::releaseSavepoint — 設定されたセーブポイントをリリースする

### 説明

public function 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::rollback

(No version information available, might only be in Git)

Session::rollback — トランザクションをロールバックする

### 説明

public function 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::rollbackTo

(No version information available, might only be in Git)

Session::rollbackTo — セーブポイントまでトランザクションをロールバックする

### 説明

public function 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::setSavepoint

(No version information available, might only be in Git)

Session::setSavepoint — セーブポイントを作成する

### 説明

public function 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();
    ?>

# Session::sql

(No version information available, might only be in Git)

Session::sql — SQLクエリを作成する

### 説明

public function 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::startTransaction

(No version information available, might only be in Git)

Session::startTransaction — トランザクションを開始する

### 説明

public function 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();
    ?>

## 目次

- 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 — トランザクションを開始する

# SqlStatement クラス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

## クラス概要

class mysql_xdevapi\SqlStatement {
/* 定数 */
const int EXECUTE_ASYNC = 1;
const int BUFFERED = 2;
/* プロパティ */
public $statement;
/* メソッド */
public function bind(string `$param`): mysql_xdevapi\SqlStatement
public function execute(): mysql_xdevapi\Result
public function getNextResult(): mysql_xdevapi\Result
public function getResult(): mysql_xdevapi\Result
public function hasMoreResults(): bool
}

## プロパティ

statement

## 定義済み定数

`mysql_xdevapi\SqlStatement::EXECUTE_ASYNC`

`mysql_xdevapi\SqlStatement::BUFFERED`

# SqlStatement::bind

(No version information available, might only be in Git)

SqlStatement::bind — ステートメントのパラメータをバインドする

### 説明

public function mysql_xdevapi\SqlStatement::bind(string `$param`): mysql_xdevapi\SqlStatement

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`param`

### 戻り値

### 例

例1 mysql_xdevapi\SqlStatement::bind() の例

    <?php

    /* ... */

    ?>

# SqlStatement::__construct

(No version information available, might only be in Git)

SqlStatement::__construct — SqlStatement のコンストラクタ

### 説明

private function mysql_xdevapi\SqlStatement::__construct()

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 例

例1 mysql_xdevapi\SqlStatement::__construct() の例

    <?php

    /* ... */

    ?>

# SqlStatement::execute

(No version information available, might only be in Git)

SqlStatement::execute — 操作を実行する

### 説明

public function mysql_xdevapi\SqlStatement::execute(): mysql_xdevapi\Result

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

### 例

例1 mysql_xdevapi\SqlStatement::execute() の例

    <?php

    /* ... */

    ?>

# SqlStatement::getNextResult

(No version information available, might only be in Git)

SqlStatement::getNextResult — 次の結果を取得する

### 説明

public function mysql_xdevapi\SqlStatement::getNextResult(): mysql_xdevapi\Result

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

### 例

例1 mysql_xdevapi\SqlStatement::getNextResult() の例

    <?php

    /* ... */

    ?>

# SqlStatement::getResult

(No version information available, might only be in Git)

SqlStatement::getResult — 結果を取得する

### 説明

public function mysql_xdevapi\SqlStatement::getResult(): mysql_xdevapi\Result

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

### 例

例1 mysql_xdevapi\SqlStatement::getResult() の例

    <?php

    /* ... */

    ?>

# SqlStatement::hasMoreResults

(No version information available, might only be in Git)

SqlStatement::hasMoreResults — さらに結果があるかを調べる

### 説明

public function mysql_xdevapi\SqlStatement::hasMoreResults(): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

結果セットがさらにフェッチするオブジェクトを持っていれば `true` を返します

### 例

例1 mysql_xdevapi\SqlStatement::hasMoreResults() の例

    <?php

    /* ... */

    ?>

## 目次

- SqlStatement::bind — ステートメントのパラメータをバインドする
- SqlStatement::__construct — SqlStatement のコンストラクタ
- SqlStatement::execute — 操作を実行する
- SqlStatement::getNextResult — 次の結果を取得する
- SqlStatement::getResult — 結果を取得する
- SqlStatement::hasMoreResults — さらに結果があるかを調べる

# SqlStatementResult クラス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

## クラス概要

class mysql_xdevapi\SqlStatementResult implements mysql_xdevapi\BaseResult, Traversable {
/* メソッド */
public function fetchAll(): array
public function fetchOne(): array
public function getAffectedItemsCount(): int
public function getColumnsCount(): int
public function getColumnNames(): array
public function getColumns(): Array
public function getGeneratedIds(): array
public function getLastInsertId(): String
public function getWarnings(): array
public function getWarningCounts(): int
public function hasData(): bool
public function nextResult(): mysql_xdevapi\Result
}

# SqlStatementResult::__construct

(No version information available, might only be in Git)

SqlStatementResult::__construct — SqlStatementResult のコンストラクタ

### 説明

private function mysql_xdevapi\SqlStatementResult::__construct()

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 例

例1 mysql_xdevapi\SqlStatementResult::__construct() の例

    <?php

    /* ... */

    ?>

# SqlStatementResult::fetchAll

(No version information available, might only be in Git)

SqlStatementResult::fetchAll — 結果セットから全行取得する

### 説明

public function 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::fetchOne

(No version information available, might only be in Git)

SqlStatementResult::fetchOne — 単一の行を取得する

### 説明

public function 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::getAffectedItemsCount

(No version information available, might only be in Git)

SqlStatementResult::getAffectedItemsCount — 影響を受けた行数を取得する

### 説明

public function mysql_xdevapi\SqlStatementResult::getAffectedItemsCount(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

### 例

例1 mysql_xdevapi\SqlStatementResult::getAffectedItemsCount() の例

    <?php

    /* ... */

    ?>

# SqlStatementResult::getColumnsCount

(No version information available, might only be in Git)

SqlStatementResult::getColumnsCount — カラムの数を取得する

### 説明

public function mysql_xdevapi\SqlStatementResult::getColumnsCount(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

カラムの数を返します。存在しない場合は、0を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.14 | メソッド名が、getColumnCount() から getColumnsCount() に変わりました。

### 例

例1 mysql_xdevapi\SqlStatementResult::getColumnsCount() の例

    <?php

    /* ... */

    ?>

# SqlStatementResult::getColumnNames

(No version information available, might only be in Git)

SqlStatementResult::getColumnNames — カラム名を取得する

### 説明

public function mysql_xdevapi\SqlStatementResult::getColumnNames(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

### 例

例1 mysql_xdevapi\SqlStatementResult::getColumnNames() の例

    <?php

    /* ... */

    ?>

# SqlStatementResult::getColumns

(No version information available, might only be in Git)

SqlStatementResult::getColumns — カラムを取得する

### 説明

public function mysql_xdevapi\SqlStatementResult::getColumns(): Array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

### 例

例1 mysql_xdevapi\SqlStatementResult::getColumns() の例

    <?php

    /* ... */

    ?>

# SqlStatementResult::getGeneratedIds

(No version information available, might only be in Git)

SqlStatementResult::getGeneratedIds — 生成された id を取得する

### 説明

public function mysql_xdevapi\SqlStatementResult::getGeneratedIds(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

直近の操作で生成された _id の配列を返します。 生成された _id がなければ、空の配列を返します。

### 例

例1 mysql_xdevapi\SqlStatementResult::getGeneratedIds() の例

    <?php

    /* ... */

    ?>

# SqlStatementResult::getLastInsertId

(No version information available, might only be in Git)

SqlStatementResult::getLastInsertId — 最後に挿入されたidを取得する

### 説明

public function mysql_xdevapi\SqlStatementResult::getLastInsertId(): String

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

最後に挿入された操作のIDを返します。

### 例

例1 mysql_xdevapi\SqlStatementResult::getLastInsertId() の例

    <?php

    /* ... */

    ?>

# SqlStatementResult::getWarnings

(No version information available, might only be in Git)

SqlStatementResult::getWarnings — 直近の操作から発生した警告を取得する

### 説明

public function mysql_xdevapi\SqlStatementResult::getWarnings(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

直近の操作によって発生した警告の数を返します。 個々のオブジェクトは、エラーの 'message', 'level' そして 'code' を定義しています。 エラーが発生しなかった場合は空の配列が返されます。

### 例

例1 mysql_xdevapi\SqlStatementResult::getWarnings() の例

    <?php

    /* ... */

    ?>

# SqlStatementResult::getWarningsCount

(No version information available, might only be in Git)

SqlStatementResult::getWarningsCount — 直近の操作で発生した警告の数を取得する

### 説明

public function mysql_xdevapi\SqlStatementResult::getWarningCounts(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

直近のCRUD操作の間に発生した警告の数を返します。

### 例

例1 mysql_xdevapi\SqlStatementResult::getWarningsCount() の例

    <?php

    /* ... */

    ?>

# SqlStatementResult::hasData

(No version information available, might only be in Git)

SqlStatementResult::hasData — 結果がデータを持っているかを調べる

### 説明

public function mysql_xdevapi\SqlStatementResult::hasData(): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

結果がデータを持っていれば `true` を返します。

### 例

例1 mysql_xdevapi\SqlStatementResult::hasData() の例

    <?php

    /* ... */

    ?>

# SqlStatementResult::nextResult

(No version information available, might only be in Git)

SqlStatementResult::nextResult — 次の結果を取得する

### 説明

public function mysql_xdevapi\SqlStatementResult::nextResult(): mysql_xdevapi\Result

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

結果セットから、次の Result オブジェクトを返します。

### 例

例1 mysql_xdevapi\SqlStatementResult::nextResult() の例

    <?php

    /* ... */

    ?>

## 目次

- 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 — 次の結果を取得する

# Statement クラス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

## クラス概要

class mysql_xdevapi\Statement {
/* 定数 */
const int EXECUTE_ASYNC = 1;
const int BUFFERED = 2;
/* メソッド */
public function getNextResult(): mysql_xdevapi\Result
public function getResult(): mysql_xdevapi\Result
public function hasMoreResults(): bool
}

## 定義済み定数

`mysql_xdevapi\Statement::EXECUTE_ASYNC`

`mysql_xdevapi\Statement::BUFFERED`

# Statement::__construct

(No version information available, might only be in Git)

Statement::__construct — Statement のコンストラクタ

### 説明

private function mysql_xdevapi\Statement::__construct()

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 例

例1 mysql_xdevapi\Statement::__construct() の例

    <?php

    /* ... */

    ?>

# Statement::getNextResult

(No version information available, might only be in Git)

Statement::getNextResult — 次の結果を取得する

### 説明

public function mysql_xdevapi\Statement::getNextResult(): mysql_xdevapi\Result

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

### 例

例1 mysql_xdevapi\Statement::getNextResult() の例

    <?php

    /* ... */

    ?>

# Statement::getResult

(No version information available, might only be in Git)

Statement::getResult — 結果を取得する

### 説明

public function mysql_xdevapi\Statement::getResult(): mysql_xdevapi\Result

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

### 例

例1 mysql_xdevapi\Statement::getResult() の例

    <?php

    /* ... */

    ?>

# Statement::hasMoreResults

(No version information available, might only be in Git)

Statement::hasMoreResults — さらに結果があるかを調べる

### 説明

public function mysql_xdevapi\Statement::hasMoreResults(): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

### 例

例1 mysql_xdevapi\Statement::hasMoreResults() の例

    <?php

    /* ... */

    ?>

## 目次

- Statement::__construct — Statement のコンストラクタ
- Statement::getNextResult — 次の結果を取得する
- Statement::getResult — 結果を取得する
- Statement::hasMoreResults — さらに結果があるかを調べる

# Table クラス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

INSERT/SELECT/UPDATE/DELETE ステートメントを通じて、テーブルへのアクセスを提供します。

## クラス概要

class mysql_xdevapi\Table implements mysql_xdevapi\SchemaObject {
/* プロパティ */
public $name;
/* メソッド */
public function count(): int
public function delete(): mysql_xdevapi\TableDelete
public function existsInDatabase(): bool
public function getName(): string
public function getSchema(): mysql_xdevapi\Schema
public function getSession(): mysql_xdevapi\Session
public function insert(mixed `$columns`, mixed `...$more_columns`): mysql_xdevapi\TableInsert
public function isView(): bool
public function select(mixed `$columns`, mixed `...$more_columns`): mysql_xdevapi\TableSelect
public function update(): mysql_xdevapi\TableUpdate
}

## プロパティ

name

# Table::__construct

(No version information available, might only be in Git)

Table::__construct — Table のコンストラクタ

### 説明

private function 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::count

(No version information available, might only be in Git)

Table::count — 行の数を取得する

### 説明

public function 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::delete

(No version information available, might only be in Git)

Table::delete — テーブルから行を削除する

### 説明

public function 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::existsInDatabase

(No version information available, might only be in Git)

Table::existsInDatabase — テーブルがデータベースに存在するかをチェックする

### 説明

public function 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::getName

(No version information available, might only be in Git)

Table::getName — テーブル名を取得する

### 説明

public function 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::getSchema

(No version information available, might only be in Git)

Table::getSchema — テーブルスキーマを取得する

### 説明

public function 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::getSession

(No version information available, might only be in Git)

Table::getSession — テーブルを操作するためのセッションを取得する

### 説明

public function 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::insert

(No version information available, might only be in Git)

Table::insert — テーブルに行を挿入する

### 説明

public function 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::isView

(No version information available, might only be in Git)

Table::isView — テーブルがビューかどうかを調べる

### 説明

public function 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::select

(No version information available, might only be in Git)

Table::select — テーブルから行を選択する

### 説明

public function 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::update

(No version information available, might only be in Git)

Table::update — テーブルの行を更新する

### 説明

public function 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();
    ?>

## 目次

- Table::__construct — Table のコンストラクタ
- Table::count — 行の数を取得する
- Table::delete — テーブルから行を削除する
- Table::existsInDatabase — テーブルがデータベースに存在するかをチェックする
- Table::getName — テーブル名を取得する
- Table::getSchema — テーブルスキーマを取得する
- Table::getSession — テーブルを操作するためのセッションを取得する
- Table::insert — テーブルに行を挿入する
- Table::isView — テーブルがビューかどうかを調べる
- Table::select — テーブルから行を選択する
- Table::update — テーブルの行を更新する

# TableDelete クラス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

テーブルのレコードを削除する操作を行うためのステートメントです。

## クラス概要

class mysql_xdevapi\TableDelete implements mysql_xdevapi\Executable {
/* メソッド */
public function bind(array `$placeholder_values`): mysql_xdevapi\TableDelete
public function execute(): mysql_xdevapi\Result
public function limit(int `$rows`): mysql_xdevapi\TableDelete
public function orderby(string `$orderby_expr`): mysql_xdevapi\TableDelete
public function where(string `$where_expr`): mysql_xdevapi\TableDelete
}

# TableDelete::bind

(No version information available, might only be in Git)

TableDelete::bind — delete のクエリパラメータをバインドする

### 説明

public function 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::__construct

(No version information available, might only be in Git)

TableDelete::__construct — TableDelete のコンストラクタ

### 説明

private function 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();

    ?>

# TableDelete::execute

(No version information available, might only be in Git)

TableDelete::execute — delete文を実行する

### 説明

public function 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::limit

(No version information available, might only be in Git)

TableDelete::limit — 削除する行を限定する

### 説明

public function 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::orderby

(No version information available, might only be in Git)

TableDelete::orderby — 削除の際のソート条件を設定する

### 説明

public function 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::where

(No version information available, might only be in Git)

TableDelete::where — 削除時の検索条件を設定する

### 説明

public function 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();

    ?>

## 目次

- TableDelete::bind — delete のクエリパラメータをバインドする
- TableDelete::__construct — TableDelete のコンストラクタ
- TableDelete::execute — delete文を実行する
- TableDelete::limit — 削除する行を限定する
- TableDelete::orderby — 削除の際のソート条件を設定する
- TableDelete::where — 削除時の検索条件を設定する

# TableInsert クラス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

テーブルにレコードを挿入する操作を行うステートメントです

## クラス概要

class mysql_xdevapi\TableInsert implements mysql_xdevapi\Executable {
/* メソッド */
public function execute(): mysql_xdevapi\Result
public function values(array `$row_values`): mysql_xdevapi\TableInsert
}

# TableInsert::__construct

(No version information available, might only be in Git)

TableInsert::__construct — TableInsert クラスのコンストラクタ

### 説明

private function 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();
    ?>

# TableInsert::execute

(No version information available, might only be in Git)

TableInsert::execute — insert クエリを実行する

### 説明

public function 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::values

(No version information available, might only be in Git)

TableInsert::values — 挿入する行の値を追加する

### 説明

public function 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();
    ?>

## 目次

- TableInsert::__construct — TableInsert クラスのコンストラクタ
- TableInsert::execute — insert クエリを実行する
- TableInsert::values — 挿入する行の値を追加する

# TableSelect クラス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

テーブルからレコードを取得する操作を行うステートメントです

## クラス概要

class mysql_xdevapi\TableSelect implements mysql_xdevapi\Executable {
/* メソッド */
public function bind(array `$placeholder_values`): mysql_xdevapi\TableSelect
public function execute(): mysql_xdevapi\RowResult
public function groupBy(mixed `$sort_expr`): mysql_xdevapi\TableSelect
public function having(string `$sort_expr`): mysql_xdevapi\TableSelect
public function limit(int `$rows`): mysql_xdevapi\TableSelect
public function lockExclusive(int `$lock_waiting_option` = ?): mysql_xdevapi\TableSelect
public function lockShared(int `$lock_waiting_option` = ?): mysql_xdevapi\TableSelect
public function offset(int `$position`): mysql_xdevapi\TableSelect
public function orderby(mixed `$sort_expr`, mixed `...$sort_exprs`): mysql_xdevapi\TableSelect
public function where(string `$where_expr`): mysql_xdevapi\TableSelect
}

# TableSelect::bind

(No version information available, might only be in Git)

TableSelect::bind — select のクエリパラメータをバインドする

### 説明

public function 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::__construct

(No version information available, might only be in Git)

TableSelect::__construct — TableSelect のコンストラクタ

### 説明

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

# TableSelect::execute

(No version information available, might only be in Git)

TableSelect::execute — select ステートメントを実行する

### 説明

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

# TableSelect::groupBy

(No version information available, might only be in Git)

TableSelect::groupBy — select 時のグループ化の条件を設定する

### 説明

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

# TableSelect::having

(No version information available, might only be in Git)

TableSelect::having — select 句の having 条件を設定する

### 説明

public function 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::limit

(No version information available, might only be in Git)

TableSelect::limit — 選択される行の数を限定する

### 説明

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

# TableSelect::lockExclusive

(No version information available, might only be in Git)

TableSelect::lockExclusive — EXCLUSIVE LOCK を実行する

### 説明

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

# TableSelect::lockShared

(No version information available, might only be in Git)

TableSelect::lockShared — SHARED LOCK を実行する

### 説明

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

# TableSelect::offset

(No version information available, might only be in Git)

TableSelect::offset — スキップするoffsetを設定する

### 説明

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

# TableSelect::orderby

(No version information available, might only be in Git)

TableSelect::orderby — select 文のソート条件を設定する

### 説明

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

# TableSelect::where

(No version information available, might only be in Git)

TableSelect::where — select 文の検索条件を設定する

### 説明

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

## 目次

- 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 文の検索条件を設定する

# TableUpdate クラス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

テーブル上のレコードを更新する操作を行うステートメントです。

## クラス概要

class mysql_xdevapi\TableUpdate implements mysql_xdevapi\Executable {
/* メソッド */
public function bind(array `$placeholder_values`): mysql_xdevapi\TableUpdate
public function execute(): mysql_xdevapi\TableUpdate
public function limit(int `$rows`): mysql_xdevapi\TableUpdate
public function orderby(mixed `$orderby_expr`, mixed `...$orderby_exprs`): mysql_xdevapi\TableUpdate
public function set(string `$table_field`, string `$expression_or_literal`): mysql_xdevapi\TableUpdate
public function where(string `$where_expr`): mysql_xdevapi\TableUpdate
}

# TableUpdate::bind

(No version information available, might only be in Git)

TableUpdate::bind — update のクエリパラメータをバインドする

### 説明

public function 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::__construct

(No version information available, might only be in Git)

TableUpdate::__construct — TableUpdate のコンストラクタ

### 説明

private function 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();

    ?>

# TableUpdate::execute

(No version information available, might only be in Git)

TableUpdate::execute — update クエリを実行する

### 説明

public function 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::limit

(No version information available, might only be in Git)

TableUpdate::limit — 更新する行の数を限定する

### 説明

public function 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::orderby

(No version information available, might only be in Git)

TableUpdate::orderby — ソート条件を設定する

### 説明

public function 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::set

(No version information available, might only be in Git)

TableUpdate::set — 更新されるフィールドを追加する

### 説明

public function 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::where

(No version information available, might only be in Git)

TableUpdate::where — 検索フィルタを設定する

### 説明

public function 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();

    ?>

## 目次

- TableUpdate::bind — update のクエリパラメータをバインドする
- TableUpdate::__construct — TableUpdate のコンストラクタ
- TableUpdate::execute — update クエリを実行する
- TableUpdate::limit — 更新する行の数を限定する
- TableUpdate::orderby — ソート条件を設定する
- TableUpdate::set — 更新されるフィールドを追加する
- TableUpdate::where — 検索フィルタを設定する

# Warning クラス

(PECL mysql-xdevapi >= 8.0.11)

## はじめに

## クラス概要

class mysql_xdevapi\Warning {
/* プロパティ */
public $message;
public $level;
public $code;
/* Constructor */
private function __construct()
}

## プロパティ

message

level

code

# Warning::__construct

(No version information available, might only be in Git)

Warning::__construct — Warning のコンストラクタ

### 説明

private function mysql_xdevapi\Warning::__construct()

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 例

例1 mysql_xdevapi\Warning::__construct() の例

    <?php

    /* ... */

    ?>

## 目次

- Warning::__construct — Warning のコンストラクタ

- インストール/設定
  - 要件
  - インストール手順
  - 実行時設定
  - ソースコードからビルド / コンパイルする
- 定義済み定数
- 変更履歴
- 例
- 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 API

# はじめに

この拡張モジュールは 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/にあります。

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定
- リソース型

## 要件

以下の関数を利用可能とするには、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 | Description
--- | --- | ---

# 定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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 拡張モジュールの概要を示す例

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

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

### 説明

function 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_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()

### 説明

function 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_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` の代入

### 説明

function 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_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()

### 説明

function 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_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()

### 説明

function 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_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`

### 説明

function 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`
  評価された結果を示す resource。この結果は、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_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()`

### 説明

function 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_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()

### 説明

function 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_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` クエリーを実行

### 説明

function 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_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()

### 説明

function 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_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()

### 説明

function 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_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()

### 説明

function 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_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()

### 説明

function mysql_fetch_array(resource `$result`, int `$result_type` = MYSQL_BOTH): array

取得した行に対応する配列を返し、内部のデータポインタを前に進めます。

### パラメータ

`result`
  評価された結果を示す resource。この結果は、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_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` を指定する

### 説明

function mysql_fetch_assoc(resource `$result`): array

取得した行に対応する連想配列を返し、内部のデータポインタを前に進めます。 mysql_fetch_assoc() は、 mysql_fetch_array() の 2 番目のパラメータを MYSQL_ASSOC に指定してコールするのと同じ働きをします。つまり、 連想配列のみを返します。

### パラメータ

`result`
  評価された結果を示す resource。この結果は、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_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()

### 説明

function mysql_fetch_field(resource `$result`, int `$field_offset` = 0): object

フィールド情報を含むオブジェクトを返します。特定のクエリー結果の中の フィールドに関する情報を得るために使用可能です。

### パラメータ

`result`
  評価された結果を示す resource。この結果は、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_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()

### 説明

function 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`
  評価された結果を示す resource。この結果は、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_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` を指定する

### 説明

function mysql_fetch_object(resource `$result`, string `$class_name` = ?, array `$params` = ?): object

取得された行を表すプロパティを有するオブジェクトを返し、 内部のデータポインタを前に進めます。

### パラメータ

`result`
  評価された結果を示す resource。この結果は、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_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` を指定する

### 説明

function mysql_fetch_row(resource `$result`): array

取得された行に対応する配列を返し、内部のデータポインタを前に進めます。

### パラメータ

`result`
  評価された結果を示す resource。この結果は、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_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]

### 説明

function mysql_field_flags(resource `$result`, int `$field_offset`): string|false

mysql_field_flags()は、指定したフィールドの フィールドフラグを返します。個々のフラグは、空白一つで区切られた 形式で返されます。このため、返された値を explode() で分割することができます。

### パラメータ

`result`
  評価された結果を示す resource。この結果は、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_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]

### 説明

function mysql_field_len(resource `$result`, int `$field_offset`): int|false

mysql_field_len()は指定したフィールドの長さを 返します。

### パラメータ

`result`
  評価された結果を示す resource。この結果は、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_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]

### 説明

function mysql_field_name(resource `$result`, int `$field_offset`): string|false

mysql_field_name()は、指定したフィールドの 名前を返します。

### パラメータ

`result`
  評価された結果を示す resource。この結果は、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_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` パラメータを使う

### 説明

function mysql_field_seek(resource `$result`, int `$field_offset`): bool

指定したフィールドオフセットに移動します。 mysql_field_seek() をコールした後、 mysql_fetch_field() をフィールドオフセットを付けずに コールした場合、このフィールドが返されます。

### パラメータ

`result`
  評価された結果を示す resource。この結果は、mysql_query() のコールにより得られたものです。
`field_offset`
  数値フィールドオフセット。`field_offset` は `0` から始まります。`field_offset` が存在しない場合、`E_WARNING` レベルのエラーが発行されます。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- mysql_fetch_field() - 結果からカラム情報を取得し、オブジェクトとして返す

# 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]

### 説明

function mysql_field_table(resource `$result`, int `$field_offset`): string

指定したフィールドが含まれるテーブルの名前を返します。

### パラメータ

`result`
  評価された結果を示す resource。この結果は、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_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]

### 説明

function mysql_field_type(resource `$result`, int `$field_offset`): string

mysql_field_type() は、 mysql_field_name() 関数に似ています。 引数は同じですが、この関数ではフィールドの型が返されます。

### パラメータ

`result`
  評価された結果を示す resource。この結果は、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_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()

### 説明

function mysql_free_result(resource `$result`): bool

mysql_free_result() は、結果 ID `result` に関するすべてのメモリを開放します。

mysql_free_result() は、 スクリプト実行のメモリの使用量が多すぎると懸念される場合にのみ 必要になります。指定した結果 ID に関する全ての結果保持用メモリは、 スクリプトの実行後に自動的に開放されます。

### パラメータ

`result`
  評価された結果を示す resource。この結果は、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_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` を指定する

### 説明

function 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_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` を指定する

### 説明

function 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_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()

### 説明

function 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_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` を指定する

### 説明

function 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_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()

### 説明

function 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() - 現在のシステムの状態を取得する

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

### 説明

function 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_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`

### 説明

function 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_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`

### 説明

function 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_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()

### 説明

function 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_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`

### 説明

function 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() などの関数を利用してください。

### 例

例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_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()

### 説明

function mysql_num_fields(resource `$result`): int|false

クエリから、フィールドの数を取得します。

### パラメータ

`result`
  評価された結果を示す resource。この結果は、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_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()

### 説明

function mysql_num_rows(resource `$result`): int|false

結果セットから行の数を取得します。このコマンドは、 SELECT や SHOW のような、実際に結果セットを返す文に対してのみ有効です。 INSERT、UPDATE、REPLACE、DELETE クエリで変更された行の数を得るには、 mysql_affected_rows() を使用してください。

### パラメータ

`result`
  評価された結果を示す resource。この結果は、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_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` を指定

### 説明

function 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_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()

### 説明

function 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_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()

### 説明

function 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 クエリを送信するが、結果に対してのフェッチやバッファリングは行わない

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

### 説明

function 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_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()

### 説明

function mysql_result(resource `$result`, int `$row`, mixed `$field` = 0): string

MySQL の結果セットからひとつのセルの内容を取得します。

大量の結果セットで作業を行う際は、行全体を取り込む関数のうちひとつを 使用することを検討するべきです（以下で説明します）。 これらの関数は一回の関数コールで複数のセルの内容を返すので、 mysql_result() よりもかなり高速です。 また、フィールド引数としてオフセット数値を指定する方が フィールド名やテーブル名.フィールド名のように指定するよりも かなり高速です。

### パラメータ

`result`
  評価された結果を示す resource。この結果は、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_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 で指定)

### 説明

function 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_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` などとする

### 説明

function 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_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` を指定する

### 説明

function 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_tablename

(PHP 4, PHP 5)

mysql_tablename — フィールドのテーブル名を得る

警告

この拡張モジュールは PHP 5.5.0 で非推奨になり、PHP 7.0.0 で削除されました。 MySQLi あるいは PDO_MySQL を使うべきです。詳細な情報は MySQL: API の選択 を参照ください。 この関数の代替として、これらが使えます。

- SQL クエリー: `SHOW TABLES`

### 説明

function 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 のコール結果からデータベース名を取得する

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

### 説明

function 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_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 を参照

### 説明

function 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_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 関数
  - 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 Native Driver

# はじめに

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
    [その他のオプション]

Autotoolsでは、 --with-openssl オプションを使用して `openssl` 拡張機能とともにビルドする場合、 `mysqlnd` の拡張SSLサポートは自動的に有効になります。 `openssl` 拡張機能なしでビルドする場合は、--with-mysqlnd-ssl Autotools オプションを使用することで、明示的に拡張SSLサポートを有効化できます。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `openssl` 拡張機能なしでビルドする場合に、拡張SSLサポートを明示的に有効にできるよう、 --with-mysqlnd-ssl Autotools 設定オプションが、追加されました。

# 実行時設定

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 でしか使えません。

`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` を使用します。

# 統計情報

MySQL Native Driver は、クライアントとサーバー間の通信に関する 統計情報の収集をサポートしています。 収集される統計情報は、主に以下の 2 種類です。

- クライアント統計情報
- 接続統計情報

mysqli 拡張モジュールを使用している場合、 これらの統計情報は以下の 2 つの API 呼び出しで取得できます。

- mysqli_get_client_stats()
- mysqli_get_connection_stats()

> 注意: 統計情報は、MySQL Native Driver を使用するすべての拡張モジュール間で 集約されます。 たとえば、mysqli 拡張モジュールと PDO MySQL ドライバの両方が MySQLnd を使用するように 設定されている場合、mysqli の関数呼び出しと PDO のメソッド呼び出しの両方が統計情報に影響します。 MySQL Native Driver を利用する各拡張モジュールの API 呼び出しが、個々の統計情報にどの程度影響しているかを特定することはできません。

## 統計情報の取得

クライアント統計情報は、 mysqli_get_client_stats() 関数を呼び出すことで取得できます。

接続統計情報は、 mysqli_get_connection_stats() 関数を呼び出すことで取得できます。

どちらの関数も連想配列を返します。 統計項目の名前が、対応する統計データのキーになっています。

## MySQL Native Driver の統計情報

ほとんどの統計情報は接続に関連付けられますが、 一部はプロセスに関連付けられます。その場合はその旨が記載されます。

MySQL Native Driver が生成する統計情報を以下に示します。

ネットワーク関連の統計情報
`bytes_sent`
  PHP から MySQL サーバーに送信されたバイト数。
`bytes_received`
  MySQL サーバーから受信したバイト数。
`packets_sent`
  MySQL クライアントサーバープロトコルで送信されたパケット数。
`packets_received`
  MySQL クライアントサーバープロトコルで受信したパケット数。
`protocol_overhead_in`
  MySQL クライアントサーバープロトコルの受信トラフィックにおけるオーバーヘッド（バイト単位）。 現在はパケットヘッダ（4 バイト）のみがオーバーヘッドとみなされます。 `protocol_overhead_in = packets_received * 4`
`protocol_overhead_out`
  MySQL クライアントサーバープロトコルの送信トラフィックにおけるオーバーヘッド（バイト単位）。 現在はパケットヘッダ（4 バイト）のみがオーバーヘッドとみなされます。 `protocol_overhead_out = packets_received * 4`
`bytes_received_ok_packet`
  受信した MySQL クライアントサーバープロトコルの OK パケットの合計サイズ（バイト単位）。 OK パケットにはステータスメッセージを含めることができます。 ステータスメッセージの長さは可変であるため、OK パケットのサイズは固定ではありません。

  > 注意: 合計サイズ（バイト単位）にはヘッダパケットのサイズ （4 バイト。プロトコルオーバーヘッドを参照）が含まれます。

`packets_received_ok`
  受信した MySQL クライアントサーバープロトコルの OK パケットの数。
`bytes_received_eof_packet`
  受信した MySQL クライアントサーバープロトコルの EOF パケットの合計サイズ（バイト単位）。 EOF のサイズはサーバーのバージョンによって異なる場合があります。 また、EOF はエラーメッセージを転送することもあります。

  > 注意: 合計サイズ（バイト単位）にはヘッダパケットのサイズ （4 バイト。プロトコルオーバーヘッドを参照）が含まれます。

`packets_received_eof`
  MySQL クライアントサーバープロトコルの EOF パケットの数。 他のパケット統計情報と同様に、PHP が期待するパケットではなく たとえばエラーメッセージを受信した場合でもパケット数は増加します。
`bytes_received_rset_header_packet`
  受信した MySQL クライアントサーバープロトコルの結果セットのヘッダパケット 合計サイズ（バイト単位）。 パケットのサイズはペイロード （`LOAD LOCAL INFILE`、`INSERT`、 `UPDATE`、`SELECT`、エラーメッセージ）によって異なります。

  > 注意: 合計サイズ（バイト単位）にはヘッダパケットのサイズ （4 バイト。プロトコルオーバーヘッドを参照）が含まれます。

`packets_received_rset_header`
  MySQL クライアントサーバープロトコルの結果セットのヘッダパケット数。
`bytes_received_rset_field_meta_packet`
  受信した MySQL クライアントサーバープロトコルの結果セットのメタデータ （フィールド情報）パケット合計サイズ（バイト単位）。 当然、サイズは結果セット内のフィールドによって異なります。 COM_LIST_FIELDS の場合、パケットにはエラーまたは EOF パケットが 含まれることもあります。

  > 注意: 合計サイズ（バイト単位）にはヘッダパケットのサイズ （4 バイト。プロトコルオーバーヘッドを参照）が含まれます。

`packets_received_rset_field_meta`
  MySQL クライアントサーバープロトコルの結果セットのメタデータ （フィールド情報）パケット数。
`bytes_received_rset_row_packet`
  受信した MySQL クライアントサーバープロトコルの結果セットの行データパケット 合計サイズ（バイト単位）。 パケットにはエラーまたは EOF パケットが含まれることもあります。 `rows_fetched_from_server_normal` と `rows_fetched_from_server_ps` を `bytes_received_rset_row_packet` から差し引くことで、エラーおよび EOF パケットの数を算出できます。

  > 注意: 合計サイズ（バイト単位）にはヘッダパケットのサイズ （4 バイト。プロトコルオーバーヘッドを参照）が含まれます。

`packets_received_rset_row`
  MySQL クライアントサーバープロトコルの結果セットの行データパケット数。
`bytes_received_prepare_response_packet`
  受信した MySQL クライアントサーバープロトコルのプリペアドステートメント初期化用 OK パケット（プリペアドステートメント初期化パケット）の合計サイズ（バイト単位）。 パケットにはエラーが含まれることもあります。 パケットのサイズは MySQL のバージョンによって異なります。

  > 注意: 合計サイズ（バイト単位）にはヘッダパケットのサイズ （4 バイト。プロトコルオーバーヘッドを参照）が含まれます。

`packets_received_prepare_response`
  MySQL クライアントサーバープロトコルのプリペアドステートメント初期化用 OK パケット（プリペアドステートメント初期化パケット）の数。
`bytes_received_change_user_packet`
  受信した MySQL クライアントサーバープロトコルの COM_CHANGE_USER パケットの 合計サイズ（バイト単位）。 パケットにはエラーまたは EOF が含まれることもあります。

  > 注意: 合計サイズ（バイト単位）にはヘッダパケットのサイズ （4 バイト。プロトコルオーバーヘッドを参照）が含まれます。

`packets_received_change_user`
  MySQL クライアントサーバープロトコルの COM_CHANGE_USER パケットの数。
`packets_sent_command`
  PHP から MySQL に送信された MySQL クライアントサーバープロトコルコマンドの数。 どの特定のコマンドがいくつ送信されたかを知る方法はありません。
`bytes_received_real_data_normal`
  PHP クライアントがテキストプロトコルを使用して `mysqlnd` から取得したペイロードのバイト数。 これは、プリペアドステートメントから生成されたものではなく、 PHP クライアントが取得した結果セットに含まれる実データのサイズです。 `mysqlnd` が MySQL からの結果セット全体を 取得済みであっても、この統計情報は PHP クライアントが `mysqlnd` から実際に取得したデータのみをカウントすることに 注意してください。

  値を増加させるコードの例を以下に示します。

      $mysqli = new mysqli();
      $res = $mysqli->query("SELECT 'abc'");
      $res->fetch_assoc();
      $res->close();

  フェッチ操作を行うたびに値が増加します。

  ただし、結果セットがクライアント側でバッファリングされただけで フェッチされなかった場合、以下の例のように統計情報は増加しません。

      $mysqli = new mysqli();
      $res = $mysqli->query("SELECT 'abc'");
      $res->close();

`bytes_received_real_data_ps`
  PHP クライアントがプリペアドステートメントプロトコルを使用して `mysqlnd` から取得したペイロードのバイト数。 これは、プリペアドステートメントから生成され、 PHP クライアントが取得した結果セットに含まれる実データのサイズです。 結果セットがその後 PHP クライアントによって読み取られなかった場合、値は増加しません。 `mysqlnd` が MySQL からの結果セット全体を 取得済みであっても、この統計情報は PHP クライアントが `mysqlnd` から実際に取得したデータのみをカウントすることに 注意してください。 `bytes_received_real_data_normal` も参照してください。

結果セット関連の統計情報
`result_set_queries`
  結果セットを生成したクエリの数。 結果セットを生成するクエリの例: `SELECT`、`SHOW`。 結果セットのヘッダパケットの読み取り時にエラーが発生した場合、 この統計情報は増加しません。

  > 注意: この統計情報は、PHP が MySQL に送信したクエリ数の 間接的な指標として使用できます。 これは、データベースに高い負荷をかけているクライアントの 特定に役立つ場合があります。

`non_result_set_queries`
  結果セットを生成しなかったクエリの数。 結果セットを生成しないクエリの例: `INSERT`、`UPDATE`、`LOAD DATA`。 結果セットのヘッダパケットの読み取り時にエラーが発生した場合、 この統計情報は増加しません。

  > 注意: この統計情報は、PHP が MySQL に送信したクエリ数の 間接的な指標として使用できます。 これは、データベースに高い負荷をかけているクライアントの 特定に役立つ場合があります。

`no_index_used`
  結果セットを生成したがインデックスを使用しなかったクエリの数。 （mysqld の起動オプション `--log-queries-not-using-indexes` も参照してください。）

  > 注意: これらのクエリは、 `mysqli_report(MYSQLI_REPORT_INDEX);` を呼び出すことで例外を通じて報告させることができます。 `mysqli_report(MYSQLI_REPORT_INDEX ^ MYSQLI_REPORT_STRICT);` を呼び出すことで、代わりに警告として報告させることもできます。

`bad_index_used`
  結果セットを生成したが適切なインデックスを使用しなかったクエリの数。 （mysqld の起動オプション `--log-slow-queries` も参照してください。）

  > 注意: これらのクエリは、 `mysqli_report(MYSQLI_REPORT_INDEX);` を呼び出すことで例外を通じて報告させることができます。 `mysqli_report(MYSQLI_REPORT_INDEX ^ MYSQLI_REPORT_STRICT);` を呼び出すことで、代わりに警告として報告させることもできます。

`slow_queries`
  実行に `long_query_time` 秒以上かかり、 少なくとも `min_examined_row_limit` 行の検査を 必要とした SQL 文。
  警告

  mysqli_report() を通じては報告されません。

`buffered_sets`
  通常のクエリ（つまり、プリペアドステートメント経由ではないクエリ）が返した バッファリングされた結果セットの数。

  クライアント側で結果セットをバッファリングする API 呼び出しの例: mysqli_query(), mysqli_store_result(), mysqli_stmt_get_result()

`unbuffered_sets`
  通常のクエリ（つまり、プリペアドステートメント経由ではないクエリ）が返した バッファリングされない結果セットの数。

  クライアント側で結果セットをバッファリングしない API 呼び出しの例: mysqli_use_result()

`ps_buffered_sets`
  プリペアドステートメントが返したバッファリングされた結果セットの数。

  クライアント側で結果セットをバッファリングする API 呼び出しの例: mysqli_stmt_store_result()

`ps_unbuffered_sets`
  プリペアドステートメントが返したバッファリングされない結果セットの数。 デフォルトではプリペアドステートメントはバッファリングされないため、 ほとんどのプリペアドステートメントはこの統計情報にカウントされます。
`flushed_normal_sets`
  通常のクエリ（つまり、プリペアドステートメント経由ではないクエリ）が返した 結果セットのうち、未読のデータが暗黙的にフラッシュされたものの数。

  > 注意: フラッシュはバッファリングされない結果セットでのみ発生します。 バッファリングされない結果セットは、接続上で新しいクエリを実行する前に 完全にフェッチする必要があります。そうしないと MySQL がエラーをスローします。 アプリケーションがバッファリングされない結果セットのすべての行をフェッチしなかった場合、 mysqlnd は暗黙的に結果セットをフェッチして回線をクリアします。 `rows_skipped_normal`、`rows_skipped_ps` も参照してください。

  > 暗黙的なフラッシュが発生する原因の例:

  > - クライアントアプリケーションの不具合
  > - クライアントが必要なデータを見つけた後に読み取りを中止したが、 MySQL に必要以上のレコードを計算させてしまった場合
  > - クライアントアプリケーションが予期せず停止した場合

`flushed_ps_sets`
  プリペアドステートメントが返した結果セットのうち、 未読のデータが暗黙的にフラッシュされたものの数。

  > 注意: フラッシュはバッファリングされない結果セットでのみ発生します。 バッファリングされない結果セットは、接続上で新しいクエリを実行する前に 完全にフェッチする必要があります。そうしないと MySQL がエラーをスローします。 アプリケーションがバッファリングされない結果セットのすべての行をフェッチしなかった場合、 mysqlnd は暗黙的に結果セットをフェッチして回線をクリアします。 `rows_skipped_normal`、`rows_skipped_ps` も参照してください。

  > 暗黙的なフラッシュが発生する原因の例:

  > - クライアントアプリケーションの不具合
  > - クライアントが必要なデータを見つけた後に読み取りを中止したが、 MySQL に必要以上のレコードを計算させてしまった場合
  > - クライアントアプリケーションが予期せず停止した場合

`ps_prepared_never_executed`
  準備されたが一度も実行されなかったステートメントの数。
`ps_prepared_once_executed`
  一度だけ実行されたプリペアドステートメントの数。
`rows_fetched_from_server_normal`
`rows_fetched_from_server_ps`
  サーバーからフェッチされた結果セット行の合計数。 これには、クライアントが読み取らなかったが、 バッファリングされない結果セットのフラッシュにより暗黙的にフェッチされた行も含まれます。 `packets_received_rset_row` も参照してください。
`rows_buffered_from_client_normal`
  通常のクエリから生成された、バッファリングされた行の合計数。 これは、MySQL からフェッチされ、クライアント側でバッファリングされた行の数です。

  結果をバッファリングするクエリの例:

  - mysqli_query()
  - mysqli_store_result()
`rows_buffered_from_client_ps`
  `rows_buffered_from_client_normal` と同様ですが、 プリペアドステートメント用です。
`rows_fetched_from_client_normal_buffered`
  通常のクエリで作成されたバッファリングされた結果セットから、 クライアントがフェッチした行の合計数。
`rows_fetched_from_client_ps_buffered`
  プリペアドステートメントで作成されたバッファリングされた結果セットから、 クライアントがフェッチした行の合計数。
`rows_fetched_from_client_normal_unbuffered`
  通常のクエリで作成されたバッファリングされない結果セットから、 クライアントがフェッチした行の合計数。
`rows_fetched_from_client_ps_unbuffered`
  プリペアドステートメントで作成されたバッファリングされない結果セットから、 クライアントがフェッチした行の合計数。
`rows_fetched_from_client_ps_cursor`
  プリペアドステートメントで作成されたカーソルから、 クライアントがフェッチした行の合計数。
`rows_skipped_normal`
`rows_skipped_ps`
  将来の使用のために予約されています（現在はサポートされていません）。
`copy_on_write_saved`
`copy_on_write_performed`
  これはプロセスレベルのスコープの統計情報です。 mysqlnd では、拡張モジュールが返す変数は mysqlnd の 内部ネットワーク結果バッファを指しています。 データが変更されない場合、フェッチされたデータはメモリ内に一度だけ保持されます。 ただし、データを変更する場合は、mysqlnd が コピーオンライト操作を実行します。
`explicit_free_result`
`implicit_free_result`
  これは接続レベルおよびプロセスレベルのスコープの統計情報です。 解放された結果セットの合計数。
`proto_text_fetched_null`
  通常のクエリ（MySQL テキストプロトコル）から取得した `MYSQL_TYPE_NULL` 型のカラムの合計数。
`proto_binary_fetched_null`
  プリペアドステートメント（MySQL バイナリプロトコル）から取得した `MYSQL_TYPE_NULL` 型のカラムの合計数。
`proto_text_fetched_bit`
  通常のクエリ（MySQL テキストプロトコル）から取得した `MYSQL_TYPE_BIT` 型のカラムの合計数。
`proto_binary_fetched_bit`
  プリペアドステートメント（MySQL バイナリプロトコル）から取得した `MYSQL_TYPE_BIT` 型のカラムの合計数。
`proto_text_fetched_tinyint`
  通常のクエリ（MySQL テキストプロトコル）から取得した `MYSQL_TYPE_TINY` 型のカラムの合計数。
`proto_binary_fetched_tinyint`
  プリペアドステートメント（MySQL バイナリプロトコル）から取得した `MYSQL_TYPE_TINY` 型のカラムの合計数。
`proto_text_fetched_short`
  通常のクエリ（MySQL テキストプロトコル）から取得した `MYSQL_TYPE_SHORT` 型のカラムの合計数。
`proto_binary_fetched_short`
  プリペアドステートメント（MySQL バイナリプロトコル）から取得した `MYSQL_TYPE_SHORT` 型のカラムの合計数。
`proto_text_fetched_int24`
  通常のクエリ（MySQL テキストプロトコル）から取得した `MYSQL_TYPE_INT24` 型のカラムの合計数。
`proto_binary_fetched_int24`
  プリペアドステートメント（MySQL バイナリプロトコル）から取得した `MYSQL_TYPE_INT24` 型のカラムの合計数。
`proto_text_fetched_int`
  通常のクエリ（MySQL テキストプロトコル）から取得した `MYSQL_TYPE_LONG` 型のカラムの合計数。
`proto_binary_fetched_int`
  プリペアドステートメント（MySQL バイナリプロトコル）から取得した `MYSQL_TYPE_LONG` 型のカラムの合計数。
`proto_text_fetched_bigint`
  通常のクエリ（MySQL テキストプロトコル）から取得した `MYSQL_TYPE_LONGLONG` 型のカラムの合計数。
`proto_binary_fetched_bigint`
  プリペアドステートメント（MySQL バイナリプロトコル）から取得した `MYSQL_TYPE_LONGLONG` 型のカラムの合計数。
`proto_text_fetched_decimal`
  通常のクエリ（MySQL テキストプロトコル）から取得した `MYSQL_TYPE_DECIMAL` または `MYSQL_TYPE_NEWDECIMAL` 型のカラムの合計数。
`proto_binary_fetched_decimal`
  プリペアドステートメント（MySQL バイナリプロトコル）から取得した `MYSQL_TYPE_DECIMAL` または `MYSQL_TYPE_NEWDECIMAL` 型のカラムの合計数。
`proto_text_fetched_float`
  通常のクエリ（MySQL テキストプロトコル）から取得した `MYSQL_TYPE_FLOAT` 型のカラムの合計数。
`proto_binary_fetched_float`
  プリペアドステートメント（MySQL バイナリプロトコル）から取得した `MYSQL_TYPE_FLOAT` 型のカラムの合計数。
`proto_text_fetched_double`
  通常のクエリ（MySQL テキストプロトコル）から取得した `MYSQL_TYPE_DOUBLE` 型のカラムの合計数。
`proto_binary_fetched_double`
  プリペアドステートメント（MySQL バイナリプロトコル）から取得した `MYSQL_TYPE_DOUBLE` 型のカラムの合計数。
`proto_text_fetched_date`
  通常のクエリ（MySQL テキストプロトコル）から取得した `MYSQL_TYPE_DATE` または `MYSQL_TYPE_NEWDATE` 型のカラムの合計数。
`proto_binary_fetched_date`
  プリペアドステートメント（MySQL バイナリプロトコル）から取得した `MYSQL_TYPE_DATE` または `MYSQL_TYPE_NEWDATE` 型のカラムの合計数。
`proto_text_fetched_year`
  通常のクエリ（MySQL テキストプロトコル）から取得した `MYSQL_TYPE_YEAR` 型のカラムの合計数。
`proto_binary_fetched_year`
  プリペアドステートメント（MySQL バイナリプロトコル）から取得した `MYSQL_TYPE_YEAR` 型のカラムの合計数。
`proto_text_fetched_time`
  通常のクエリ（MySQL テキストプロトコル）から取得した `MYSQL_TYPE_TIME` 型のカラムの合計数。
`proto_binary_fetched_time`
  プリペアドステートメント（MySQL バイナリプロトコル）から取得した `MYSQL_TYPE_TIME` 型のカラムの合計数。
`proto_text_fetched_datetime`
  通常のクエリ（MySQL テキストプロトコル）から取得した `MYSQL_TYPE_DATETIME` 型のカラムの合計数。
`proto_binary_fetched_datetime`
  プリペアドステートメント（MySQL バイナリプロトコル）から取得した `MYSQL_TYPE_DATETIME` 型のカラムの合計数。
`proto_text_fetched_timestamp`
  通常のクエリ（MySQL テキストプロトコル）から取得した `MYSQL_TYPE_TIMESTAMP` 型のカラムの合計数。
`proto_binary_fetched_timestamp`
  プリペアドステートメント（MySQL バイナリプロトコル）から取得した `MYSQL_TYPE_TIMESTAMP` 型のカラムの合計数。
`proto_text_fetched_string`
  通常のクエリ（MySQL テキストプロトコル）から取得した `MYSQL_TYPE_STRING`、`MYSQL_TYPE_VARSTRING`、または `MYSQL_TYPE_VARCHAR` 型のカラムの合計数。
`proto_binary_fetched_string`
  プリペアドステートメント（MySQL バイナリプロトコル）から取得した `MYSQL_TYPE_STRING`、`MYSQL_TYPE_VARSTRING`、または `MYSQL_TYPE_VARCHAR` 型のカラムの合計数。
`proto_text_fetched_blob`
  通常のクエリ（MySQL テキストプロトコル）から取得した `MYSQL_TYPE_TINY_BLOB`、 `MYSQL_TYPE_MEDIUM_BLOB`、 `MYSQL_TYPE_LONG_BLOB`、 または `MYSQL_TYPE_BLOB` 型のカラムの合計数。
`proto_binary_fetched_blob`
  プリペアドステートメント（MySQL バイナリプロトコル）から取得した `MYSQL_TYPE_TINY_BLOB`、 `MYSQL_TYPE_MEDIUM_BLOB`、 `MYSQL_TYPE_LONG_BLOB`、 または `MYSQL_TYPE_BLOB` 型のカラムの合計数。
`proto_text_fetched_enum`
  通常のクエリ（MySQL テキストプロトコル）から取得した `MYSQL_TYPE_ENUM` 型のカラムの合計数。
`proto_binary_fetched_enum`
  プリペアドステートメント（MySQL バイナリプロトコル）から取得した `MYSQL_TYPE_ENUM` 型のカラムの合計数。
`proto_text_fetched_set`
  通常のクエリ（MySQL テキストプロトコル）から取得した `MYSQL_TYPE_SET` 型のカラムの合計数。
`proto_binary_fetched_set`
  プリペアドステートメント（MySQL バイナリプロトコル）から取得した `MYSQL_TYPE_SET` 型のカラムの合計数。
`proto_text_fetched_geometry`
  通常のクエリ（MySQL テキストプロトコル）から取得した `MYSQL_TYPE_GEOMETRY` 型のカラムの合計数。
`proto_binary_fetched_geometry`
  プリペアドステートメント（MySQL バイナリプロトコル）から取得した `MYSQL_TYPE_GEOMETRY` 型のカラムの合計数。
`proto_text_fetched_other`
  通常のクエリ（MySQL テキストプロトコル）から取得した、 上記に記載されていない `MYSQL_TYPE_*` 型のカラムの合計数。

  > 注意: 理論上、これは常に `0` になるはずです。

`proto_binary_fetched_other`
  プリペアドステートメント（MySQL バイナリプロトコル）から取得した、 上記に記載されていない `MYSQL_TYPE_*` 型のカラムの合計数。

  > 注意: 理論上、これは常に `0` になるはずです。

接続関連の統計情報
`connect_success`
  成功した接続試行の合計数。

  > 注意: `connect_success` には、成功した持続的接続と 非持続的接続の試行の合計が含まれます。 したがって、成功した非持続的接続の試行数は `connect_success - pconnect_success` となります。

`pconnect_success`
  成功した持続的接続試行の合計数。
`connect_failure`
  失敗した接続試行の合計数。
`reconnect`
  これはプロセスレベルのスコープの統計情報です。
`active_connections`
  これはプロセスレベルのスコープの統計情報です。 アクティブな持続的接続と非持続的接続の合計数。

  > 注意: アクティブな非持続的接続の合計数は `active_connections - active_persistent_connections` です。

`active_persistent_connections`
  これはプロセスレベルのスコープの統計情報です。 アクティブな持続的接続の合計数。
`explicit_close`
  明示的に閉じられた接続の合計数。

  例1 明示的なクローズが発生するコードスニペットの例

  -     $link = new mysqli(/* ... */);
        $link->close(/* ... */);

  -     $link = new mysqli(/* ... */);
        $link->connect(/* ... */);

`implicit_close`
  暗黙的に閉じられた接続の合計数。

  例2 暗黙的なクローズが発生するコードスニペットの例

  -     $link = new mysqli(/* ... */);
        $link->real_connect(/* ... */);

  - `unset($link)`
  - 持続的接続: プールされた接続が real_connect で作成されており、未知のオプションが設定されている可能性がある場合、 未知のオプションが設定された接続を返すことを避けるために暗黙的にクローズする
  - 持続的接続: ping/change_user が失敗し、ext/mysqli が接続をクローズする場合
  - スクリプト実行の終了時: ユーザーが閉じなかった接続を 自動的にクローズする
`disconnect_close`
  接続確立時に C API の `mysql_real_connect` 呼び出しが示す接続失敗。
`in_middle_of_command_close`
  これはプロセスレベルのスコープの統計情報です。 コマンド実行の途中でクローズされた接続 （未取得の結果セットがある状態、クエリ送信後かつ応答受信前、 データフェッチ中、LOAD DATA でのデータ転送中）。
  警告

  非同期クエリを使用していない限り、 これは PHP アプリケーションが予期せず終了し、 PHP が自動的に接続をクローズした場合にのみ発生するはずです。

`init_command_executed_count`
  init コマンドの実行回数の合計。 例: `mysqli_options(MYSQLI_INIT_COMMAND , $value)`。 成功した実行回数は `init_command_executed_count - init_command_failed_count` です。
`init_command_failed_count`
  失敗した init コマンドの合計数。

`COM_*` コマンド関連の統計情報
`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`
  PHP から MySQL に特定の `COM_*` コマンドを送信した試行回数の合計。 統計情報は、回線の確認後、対応する MySQL クライアントサーバープロトコルパケットを 送信する直前にインクリメントされます。
  警告

  MySQLnd がパケットの送信に失敗した場合でも、統計情報はデクリメントされません。 失敗した場合、MySQLnd は PHP の警告 Error while sending %s packet. PID=%d. を発行します。

  例3 使用例

  - PHP が特定のコマンドを MySQL に送信しているかどうかを確認する。 たとえば、クライアントが `COM_PROCESS_KILL` を送信しているかどうかを確認する
  - `COM_EXECUTE` と `COM_PREPARE` を比較して、 プリペアドステートメントの平均実行回数を算出する
  - `COM_QUERY` がゼロかどうかを確認して、 PHP がプリペアドステートメント以外の SQL 文を実行していないかどうかを確認する
  - `COM_QUERY` と `COM_EXECUTE` を確認して、 過剰な数の SQL 文を実行している PHP スクリプトを特定する

その他の統計情報
`explicit_stmt_close`
`implicit_stmt_close`
  これはプロセスレベルのスコープの統計情報です。 クローズされたプリペアドステートメントの合計数。

  > 注意: プリペアドステートメントは常に明示的にクローズされます。暗黙的にクローズされるのは、 準備に失敗した場合だけです。

`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`
  これはプロセスレベルのスコープの統計情報です。 メモリ管理の呼び出し。
`command_buffer_too_small`
  PHP から MySQL にコマンドを送信する際に、ネットワークコマンドバッファが 拡張された回数。 MySQLnd は各接続に対して mysqlnd.net_cmd_buffer_size バイトの内部コマンド/ネットワークバッファを割り当てます。 MySQL クライアントサーバープロトコルコマンド、 たとえば `COM_QUERY`（通常のクエリ）が バッファに収まらない場合、 MySQLnd はコマンドの送信に必要なサイズまでバッファを拡張します。 ある接続でバッファが拡張されるたびに、 `command_buffer_too_small` が 1 増加します。 MySQLnd がほぼすべての接続で初期サイズの mysqlnd.net_cmd_buffer_size バイトを超えてバッファを拡張する必要がある場合は、 再割り当てを避けるためにデフォルトサイズの増加を検討すべきです。
`connection_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 8.3.17 という文字列フォーマットです。`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() | mysqlnd_cache.query() mysqlnd.query
ext/mysqlnd_monitor | mysqlnd_monitor.query() | mysqlnd_monitor.query() mysqlnd_cache.query() 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;
    }

- 概要
- インストール
- 実行時設定
- 非互換性
- 持続的接続
- 統計情報
- メモ
- メモリ管理
- MySQL Native Driver プラグインAPI
  - mysqlndプラグイン と MySQL Proxyの比較
  - mysqlnd plugin APIを取得する
  - MySQL Native Driverプラグイン のアーキテクチャ
  - mysqlnd のプラグインAPI
  - mysqlndプラグインの開発をはじめよう

- MySQL 用 PHP ドライバの概要
  - 用語説明
  - どの API を使うか
  - どのライブラリを選ぶか
  - コンセプト
- MySQLi — MySQL 改良版拡張モジュール
  - mysqli の概要
  - クイックスタートガイド
  - インストール/設定
  - mysqli 拡張モジュールでの持続的接続
  - 定義済み定数
  - ノート
  - MySQLi 拡張モジュールの関数概要
  - 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
  - 概要
  - インストール
  - 実行時設定
  - 非互換性
  - 持続的接続
  - 統計情報
  - メモ
  - メモリ管理
  - MySQL Native Driver プラグインAPI

# Oracle OCI8

# はじめに

警告

この拡張モジュールは、PHP 8.4.0 以降では PHP にバンドルされません。

これらの関数により、 Oracle データベースにアクセスできます。 これらは SQL 及び PL/SQL 文をサポートします。基本的なフィーチャーには、 トランザクション制御、 PHP 変数の Oracle プレースホルダへのバインディング、 及び、ラージ・オブジェクト (LOB) 型やコレクションのサポートが含まれます。 データベース常駐接続プーリング(DRCP)や結果キャッシングのような、 オラクルのスケーラビリティ・フィーチャーもサポートされます。

# インストール/設定

## 目次

- 要件
- インストール手順
- テスト
- 実行時設定

## 要件

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) 関連の定数
`OCI_FO_ABORT` (int) | フェイルオーバーは失敗し、リトライのオプションもありません
`OCI_FO_BEGIN` (int) | フェイルオーバー処理が接続の切断を検知し、 フェイルオーバー処理が開始されています。
`OCI_FO_END` (int) | フェイルオーバーは成功しました
`OCI_FO_ERROR` (int) | フェイルオーバーは失敗しましたが、 アプリケーションにはエラーを処理し、 `OCI_FO_RETRY` を返してフェイルオーバーを再試行するチャンスがあります。
`OCI_FO_NONE` (int) | ユーザーがフェイルオーバーのタイプを要求していません
`OCI_FO_REAUTH` (int) | Oracle のユーザーが再認証されました
`OCI_FO_RETRY` (int) | Oracle がフェイルオーバーを再試行すべきです。 新しい接続へのフェイルオーバー中にエラーが発生した場合、 TAF はフェイルオーバーを再試行できます。 通常、アプリケーションコードは `OCI_FO_RETRY` を返す前に しばらく待機する必要があります。
`OCI_FO_SELECT` (int) | ユーザーは SELECT のフェイルオーバーも要求しています。 これにより、開いているカーソルを持つユーザーは、 障害発生後もそのカーソルからのフェッチを継続できます。
`OCI_FO_SESSION` (int) | ユーザーはセッションのフェイルオーバーのみを要求しています。 例えば、ユーザーの接続が切断された場合、 バックアップサーバー上でそのユーザー向けに新しいセッションが自動的に作成されます。 このタイプのフェイルオーバーでは、SELECT 文の回復は試みられません。
`OCI_FO_TXNAL` (int) | ユーザーがトランザクションのフェイルオーバーを要求しました

# 例

これらの例では `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:

function 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 5 >= 5.1.2, PHP 7, PHP 8, PECL OCI8 >= 1.2.0)

oci_bind_array_by_name — PHP の配列を Oracle PL/SQL の配列に名前でバインドする

### 説明

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

    ?>

# oci_bind_by_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_bind_by_name — Oracle プレースホルダに PHP 変数をバインドする

### 説明

function 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_cancel

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_cancel — カーソルからの読み込みをキャンセルする

### 説明

function oci_cancel(resource `$statement`): bool

カーソルを無効にして関連付けられた全てのリソースを開放し、 読み込みをキャンセルします。

### パラメータ

`statement`

  OCI ステートメント

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

# oci_client_version

(PHP 5 >= 5.3.7, PHP 7, PHP 8, PECL OCI8 >= 1.4.6)

oci_client_version — Oracle クライアント・ライブラリのバージョンを返す

### 説明

function 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 データベースのバージョンを返す

# oci_close

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_close — Oracleとの接続を閉じる

### 説明

function 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_commit

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_commit — 未解決のトランザクションをコミットする

### 説明

function 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() - 未解決のデータベーストランザクションをロールバックする

# oci_connect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_connect — Oracle データベースに接続する

### 説明

function 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との接続を閉じる

# oci_define_by_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_define_by_name — PHP の変数を、クエリで取得するカラムに関連づける

### 説明

function 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_error

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_error — 最後に見つかったエラーを返す

### 説明

function 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_execute

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_execute — 文を実行する

### 説明

function 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_fetch

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch — クエリの次の行を内部バッファに取得する

### 説明

function 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_all

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_all — クエリからの複数の行を二次元配列に取得する

### 説明

function 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_array

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_array — クエリの次の行を連想配列あるいは数値添字配列で返す

### 説明

function 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_assoc

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_assoc — クエリの次の行を連想配列で返す

### 説明

function 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_object

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_object — クエリの次の行をオブジェクトとして返す

### 説明

function 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_row

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_fetch_row — クエリの次の行を配列で返す

### 説明

function 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() - クエリの次の行をオブジェクトとして返す

# oci_field_is_null

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_is_null — フェッチしたフィールドが `null` であるかどうかを確認する

### 説明

function 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_name

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_name — 文からのフィールド名を返す

### 説明

function 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_precision

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_precision — フィールドの精度を問い合わせる

### 説明

function 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_scale

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_scale — フィールドの桁数を問い合わせる

### 説明

function 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_size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_size — フィールドサイズを返す

### 説明

function 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_type

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_type — フィールドのデータ型の名前を返す

### 説明

function 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() - フィールドサイズを返す

# oci_field_type_raw

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_field_type_raw — Oracle におけるフィールドの型を問い合わせる

### 説明

function 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_free_descriptor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_free_descriptor — ディスクリプタを解放する

### 説明

function oci_free_descriptor(OCILob `$lob`): bool

oci_new_descriptor() で確保したディスクリプタを解放します。

### パラメータ

`lob`

  oci_new_descriptor() で確保したディスクリプタ。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 注意

> 注意:

> この関数は、一般に OCILOB::free メソッドとして使います。

### 参考

- OCILOB::free

# oci_free_statement

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_free_statement — 文やカーソルに関連付けられた全てのリソースを解放する

### 説明

function oci_free_statement(resource `$statement`): bool

oci_parse() の結果や Oracle から取得した、 Oracle のカーソルおよび文に関連付けられた全てのリソースを解放します。

### パラメータ

`statement`

  有効な OCI ステートメント ID。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

# oci_get_implicit_resultset

(PHP 5 >= 5.6.0, PHP 7, PHP 8, PECL OCI8 >= 2.0.0)

oci_get_implicit_resultset — Oracle Database の暗黙の結果セットを持つ親ステートメント・リソースから次の子ステートメント・リソースを返す

### 説明

function 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_lob_copy

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_lob_copy — ラージオブジェクトをコピーする

### 説明

function 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 と呼ばれていました。

# oci_lob_is_equal

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_lob_is_equal — 2 つの LOB/FILE ロケータの等価性を比較する

### 説明

function 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_new_collection

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_collection — 新しいコレクションオブジェクトを割り当てる

### 説明

function 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 と呼ばれていました。

# oci_new_connect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_connect — 一意な接続を使って Oracle サーバーへ接続する

### 説明

function 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_cursor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_cursor — 新規カーソル (ステートメントハンドル) を割り当て、それを返す

### 説明

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

    ?>

# oci_new_descriptor

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_new_descriptor — 空の新規 LOB あるいは FILE ディスクリプタを初期化する

### 説明

function 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_num_fields

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_num_fields — ある文における結果のカラム数を返す

### 説明

function 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_rows

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_num_rows — 文の実行で作用された行数を取得する

### 説明

function 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*() 関数によってバッファに取得された行数を返します。

# oci_parse

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_parse — 実行のために Oracle の文をパースする

### 説明

function 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() - 文やカーソルに関連付けられた全てのリソースを解放する

# oci_password_change

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_password_change — Oracle ユーザーのパスワードを変更する

### 説明

function oci_password_change(
resource `$connection`,
string `$username`,
string `$old_password`,
string `$new_password`
): bool
function 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 から利用可能です。

# oci_pconnect

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_pconnect — 持続的接続を使用してOracle データベースに接続する

### 説明

function 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 サーバーへ接続する

# 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

### 説明

function 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:

  function 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_result

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_result — フェッチした行からフィールドの値を取得する

### 説明

function 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_rollback

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_rollback — 未解決のデータベーストランザクションをロールバックする

### 説明

function 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() - 文を実行する

# oci_server_version

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_server_version — Oracle データベースのバージョンを返す

### 説明

function 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_set_action

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_action — アクション名を設定します

### 説明

function 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

# 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

### 説明

function oci_set_call_timeout(resource `$connection`, int `$timeout`): bool

Sets a timeout limiting the maximum 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_client_identifier

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_client_identifier — クライアント識別子を設定します

### 説明

function 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_info

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_client_info — クライアント情報を設定する

### 説明

function 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

# 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

### 説明

function 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_edition

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_edition — データベース・エディション を設定します

### 説明

function 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_module_name

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL OCI8 >= 1.4.0)

oci_set_module_name — モジュール名を設定します

### 説明

function 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_prefetch

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_set_prefetch — クエリがプリフェッチする行数を設定する

### 説明

function 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 オプション

# oci_set_prefetch_lob

(PHP 8.2, PECL OCI8 >= 3.2)

oci_set_prefetch_lob — CLOB や BLOB ごとにプリフェッチするデータサイズを設定する

### 説明

function 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_statement_type

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

oci_statement_type — ステートメントの種類を返す

### 説明

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

    ?>

# 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

### 説明

function 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

## 目次

- 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 クラス

(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 function append(string `$value`): bool
public function assign(OCICollection `$from`): bool
public function assignElem(int `$index`, string `$value`): bool
public function free(): bool
public function getElem(int `$index`): string|float|null|false
public function max(): int|false
public function size(): int|false
public function trim(int `$num`): bool
}

# OCICollection::append

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::append — コレクションに要素を追加する

### 説明

public function OCICollection::append(string `$value`): bool

コレクションの最後に要素を追加します。

### パラメータ

`value`

  コレクションに追加する値を指定します。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0, PECL OCI8 3.0.0 | OCI-Collection クラスは、 PHP の名前付けの規約に従って OCICollection に名前が変更されました。

### 参考

- OCICollection::assign

# OCICollection::assign

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::assign — コレクションに他の存在するコレクションから値を割り当てる

### 説明

public function 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::assignElem

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::assignElem — コレクションの要素に値を割り当てる

### 説明

public function 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::free

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::free — コレクションオブジェクトに関連付けられたリソースを解放する

### 説明

public function OCICollection::free(): bool

コレクションオブジェクトに関連付けられたリソースを解放します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0, PECL OCI8 3.0.0 | OCI-Collection クラスは、 PHP の名前付けの規約に従って OCICollection に名前が変更されました。

### 参考

- oci_new_collection

# OCICollection::getElem

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::getElem — 要素の値を返す

### 説明

public function 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::max

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::max — コレクション内の要素の最大数を取得する

### 説明

public function OCICollection::max(): int|false

コレクション内の要素の最大数を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

コレクション内の要素の最大数、あるいはエラー時に `false` を返します。

戻り値が 0 の場合、要素の数に制限はありません。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0, PECL OCI8 3.0.0 | OCI-Collection クラスは、 PHP の名前付けの規約に従って OCICollection に名前が変更されました。

### 参考

- OCICollection::size

# OCICollection::size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::size — コレクションのサイズを返す

### 説明

public function OCICollection::size(): int|false

コレクションのサイズを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

コレクション内の要素の数、もしくはエラー時に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0, PECL OCI8 3.0.0 | OCI-Collection クラスは、 PHP の名前付けの規約に従って OCICollection に名前が変更されました。

### 参考

- OCICollection::max

# OCICollection::trim

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCICollection::trim — コレクションの最後から要素を切り取る

### 説明

public function OCICollection::trim(int `$num`): bool

コレクションの最後から `num` 個の要素を切り取ります。

### パラメータ

`num`

  切り取る要素の数。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0, PECL OCI8 3.0.0 | OCI-Collection クラスは、 PHP の名前付けの規約に従って OCICollection に名前が変更されました。

### 参考

- OCICollection::size

## 目次

- OCICollection::append — コレクションに要素を追加する
- OCICollection::assign — コレクションに他の存在するコレクションから値を割り当てる
- OCICollection::assignElem — コレクションの要素に値を割り当てる
- OCICollection::free — コレクションオブジェクトに関連付けられたリソースを解放する
- OCICollection::getElem — 要素の値を返す
- OCICollection::max — コレクション内の要素の最大数を取得する
- OCICollection::size — コレクションのサイズを返す
- OCICollection::trim — コレクションの最後から要素を切り取る

# 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 function append(OCILob `$from`): bool
public function close(): bool
public function eof(): bool
public function erase(?int `$offset` = `null`, ?int `$length` = `null`): int|false
public function export(string `$filename`, ?int `$offset` = `null`, ?int `$length` = `null`): bool
public function flush(int `$flag` = 0): bool
public function free(): bool
public function getBuffering(): bool
public function import(string `$filename`): bool
public function load(): string|false
public function read(int `$length`): string|false
public function rewind(): bool
public function save(string `$data`, int `$offset` = 0): bool
public function seek(int `$offset`, int `$whence` = `OCI_SEEK_SET`): bool
public function setBuffering(bool `$mode`): bool
public function size(): int|false
public function tell(): int|false
public function truncate(int `$length` = 0): bool
public function write(string `$data`, ?int `$length` = `null`): int|false
public function writeTemporary(string `$data`, int `$type` = `OCI_TEMP_CLOB`): bool
}

# OCILob::append

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::append — ラージオブジェクトのデータを他のラージオブジェクトに追加する

### 説明

public function 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

# OCILob::close

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::close — LOB ディスクリプタを閉じる

### 説明

public function OCILob::close(): bool

LOB あるいは FILE のディスクリプタを閉じます。 この関数は OCILob::writeTemporary を併用した場合のみ使用されるべきです。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

### 参考

- OCILob::writeTemporary

# OCILob::eof

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::eof — ラージオブジェクトのディスクリプタが EOF かどうかを調べる

### 説明

public function 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

# OCILob::erase

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::erase — 内部 LOB データの特定の位置を消去する

### 説明

public function 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

# OCILob::export

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::export — LOB の内容をファイルに出力する

### 説明

public function 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

# OCILob::flush

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::flush — LOB のバッファをサーバーにフラッシュする、あるいは書き込む

### 説明

public function 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

# OCILob::free

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::free — LOB ディスクリプタに関連付けられたりソースを解放する

### 説明

public function OCILob::free(): bool

事前に oci_new_descriptor() を使用して割り当てられた ディスクリプタに関連付けられたりソースを解放します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

# OCILob::getBuffering

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::getBuffering — ラージオブジェクトに対する現在のバッファリングの状態を返す

### 説明

public function OCILob::getBuffering(): bool

ラージオブジェクトに対するバッファリングが有効か無効かを調べます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

もしラージオブジェクトに対するバッファリングが無効な場合は `false`、 有効な場合は `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

### 参考

- OCILob::setBuffering

# OCILob::import

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::import — ファイルデータを LOB にインポートする

### 説明

public function 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::load

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::load — ラージオブジェクトの内容を返す

### 説明

public function 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::read

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::read — ラージオブジェクトの一部を読み込む

### 説明

public function 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::rewind

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::rewind — 内部ポインタをラージオブジェクトの先頭に移動する

### 説明

public function OCILob::rewind(): bool

内部ポインタをラージオブジェクトの先頭にセットします。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

### 参考

- OCILob::seek
- OCILob::tell

# OCILob::save

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::save — データをラージオブジェクトに保存する

### 説明

public function 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::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::seek

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::seek — ラージオブジェクトの内部ポインタをセットする

### 説明

public function 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::setBuffering

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::setBuffering — 現在のラージオブジェクト用のバッファリング状態を変更する

### 説明

public function 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::size

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::size — ラージオブジェクトのサイズを返す

### 説明

public function OCILob::size(): int|false

ラージオブジェクトのサイズを取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

ラージオブジェクトのサイズを返します。 失敗した場合に `false` を返します。 空のオブジェクトは長さ 0 となります。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0, PECL OCI8 3.0.0 | OCI-Lob クラスは、 PHP の名前付けの規約に従って OCILob に名前が変更されました。

# OCILob::tell

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::tell — ラージオブジェクトの内部ポインタの現在位置を返す

### 説明

public function 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::truncate

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::truncate — ラージオブジェクトを切りつめる

### 説明

public function 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::write

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::write — データをラージオブジェクトに書き込む

### 説明

public function 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::writeTemporary

(PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.1.0)

OCILob::writeTemporary — 一時的なラージオブジェクトを書き込む

### 説明

public function 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::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 に名前が変更されました。

## 目次

- 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

(PHP 5, PHP 7, PECL OCI8 >= 1.1.0, PECL OCI8 <= 2.2.0)

oci_internal_debug — 内部的なデバッグ出力を有効/無効にする

### 説明

function oci_internal_debug(bool `$onoff`): void

内部的なデバッグ出力を有効/無効にします。

### パラメータ

`onoff`

  この値を `false` にすると、デバッグ出力がオフになり、 `true` にするとオンになります。

### 戻り値

値を返しません。

### 注意

> 注意:

> この関数は PHP 8 と PECL OCI8 3.0 からは削除されています。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# ocicancel

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicancel — oci_cancel() のエイリアス

### 説明

oci_cancel() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# ocicloselob

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 1.0)

ocicloselob — OCILob::close() のエイリアス

### 説明

OCILob::close() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# ocicollassign

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 >= 1.0.0)

ocicollassign — OCICollection::assign() のエイリアス

### 説明

OCICollection::assign() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# ocicommit

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocicommit — oci_commit() のエイリアス

### 説明

oci_commit() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# ocierror

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocierror — oci_error() のエイリアス

### 説明

oci_error() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# ociexecute

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociexecute — oci_execute() のエイリアス

### 説明

oci_execute() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# ocifetch

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifetch — oci_fetch() のエイリアス

### 説明

oci_fetch() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# ocifreedesc

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocifreedesc — OCILob::free() のエイリアス

### 説明

OCILob::free() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# ociloadlob

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociloadlob — OCILob::load() のエイリアス

### 説明

OCILob::load() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# ocilogoff

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocilogoff — oci_close() のエイリアス

### 説明

oci_close() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# ocilogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocilogon — oci_connect() のエイリアス

### 説明

oci_connect() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# ociparse

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociparse — oci_parse() のエイリアス

### 説明

oci_parse() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# ociplogon

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociplogon — oci_pconnect() のエイリアス

### 説明

oci_pconnect() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# ociresult

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociresult — oci_result() のエイリアス

### 説明

oci_result() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# ocirollback

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocirollback — oci_rollback() のエイリアス

### 説明

oci_rollback() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# ocisavelob

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisavelob — OCILob::save() のエイリアス

### 説明

OCILob::save() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# ocisavelobfile

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ocisavelobfile — OCILob::import() のエイリアス

### 説明

OCILob::import() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# 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 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# ociwritelobtofile

(PHP 4, PHP 5, PHP 7, PHP 8, PECL OCI8 >= 1.0.0)

ociwritelobtofile — OCILob::export() のエイリアス

### 説明

OCILob::export() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

# ociwritetemporarylob

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PECL OCI8 1.0)

ociwritetemporarylob — OCILob::writeTemporary() のエイリアス

### 説明

OCILob::writeTemporary() のエイリアス

警告

このエイリアスは PHP 5.4.0 で 非推奨 となりました。 このエイリアスを使用しないことを強く推奨します。

## 目次

- 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 接続のハンドリングおよびプーリング
- 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 のエイリアス

# PostgreSQL

# はじめに

PostgreSQL データベースはオープンソースの製品であり、無料で 使用可能です。Postgres は元々 UCB（カリフォルニア大学バークレイ校） コンピュータ・サイエンス学部で開発されたものです。この Postgres は、 現在いくつかの商用データベースにおいてサポートされつつある オブジェクトリレーショナルデータベース的概念の多くの先駆けでした。 Postgres は、SQL92/SQL99 言語サポート・トランザクション・参照整合性・ ストアドプロシージャ・拡張可能な型を提供しています。PostgreSQL は、 バークレイ校での Postgres のオリジナルコードの、オープンソースの 子孫にあたります。

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定
- リソース型

## 要件

PostgreSQL サポートを使用するには、libpq（PostgreSQL の C クライアント ライブラリ）が必要です。 PHP 8.0.0 以降では、libpq 9.1 以降が必要です。 PHP 8.4.0 以降では、libpq 10.0 以降が必要です。 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_TUPLES_CHUNK` (int)
  pg_result_status() から返されます。 チャンクモードでコマンドは正常に終了し、データを返しました。 pg_set_chunked_rows_size() がせっていされた場合の `SELECT` コマンドがこの値を返します。 結果セットは複数のチャンクに分割され、それぞれがあらかじめ決まった行数を持ちます。 PHP 8.4.0 以降、かつ libpq 17 以降で利用可能です。
`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.4.20 以降で利用可能です。
`PGSQL_TRACE_REGRESS_MODE` (int)
  pg_trace() に指定するために使います。 OID のようなフィールドを、トレースのメッセージに含めます。 PHP 8.3.0 以降で利用可能です。

# 例

## 目次

- 基本的な使用法
- 基本的な使い方

## 基本的な使用法

この例では、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($dbconn, $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 には、データベースのスキーマ情報（例: データベース内の すべてのテーブルなど）を取得するための特別なコマンドがありません。 その代わりに、`information_schema` という標準スキーマが存在し、必要な情報が検索しやすい形式で格納されています。 詳しい情報は » PostgreSQL Documentation を参照ください。

# pg_affected_rows

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_affected_rows — 変更されたレコード(タプル)の数を返す

### 説明

function pg_affected_rows(PgSql\Result `$result`): int

pg_affected_rows() は、INSERT, UPDATE, DELETE クエリにより変更されたタプル(インスタンス/レコード/行)の数を 返します。

SELECT を実行したときには、選択された行の数も返します。

> 注意:

> この関数は、以前は pg_cmdtuples() と呼ばれていました。

### パラメータ

`result`
  pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

### 戻り値

クエリによって変更された行の数を返します。もし変更されたタプルがない場合は `0` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | `result` は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_cancel_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_cancel_query — 非同期クエリを取り消す

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_change_password

(PHP 8 >= 8.4.0)

pg_change_password — PostgreSQL ユーザーのパスワードを変更する

### 説明

function pg_change_password(PgSql\Connection `$connection`, string `$user`, string `$password`): bool

pg_change_password() は、 PostgreSQL ユーザーのパスワードを変更します。 この関数は libpq の `PQchangePassword` 関数を使用しており、 パスワードの暗号化はサーバーの設定に基づいて自動的に処理されます。

### パラメータ

`connection`
  PgSql\Connection クラスのインスタンス。
`user`
  パスワードを変更する PostgreSQL ユーザーの名前。
`password`
  新しいパスワード。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 参考

- pg_connect() - PostgreSQL 接続をオープンする

# pg_client_encoding

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_client_encoding — クライアントのエンコーディングを取得する

### 説明

function pg_client_encoding(?PgSql\Connection `$connection` = `null`): string

PostgreSQL は、ある種の文字セットについてはサーバーとクライアントの間の 自動文字コード変換をサポートしています。 pg_client_encoding() は、クライアントの エンコーディングを文字列として返します。返される値は、標準の PostgreSQL エンコーディング識別子のなかのひとつとなります。

> 注意:

> 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
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() - クライアントのエンコーディングを設定する

# pg_close

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_close — PostgreSQL 接続をクローズする

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
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 接続をオープンする

# pg_connect

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_connect — PostgreSQL 接続をオープンする

### 説明

function 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 クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。

### 例

例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_poll

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_connect_poll — 進行中の非同期接続のステータスをポーリングする

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

# pg_connection_busy

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_busy — 接続がビジーかどうか調べる

### 説明

function pg_connection_busy(PgSql\Connection `$connection`): bool

pg_connection_busy() は、接続がビジーかどうかを調べます。 接続がビジーである場合、以前のクエリがまだ実行中です。 もしこの接続に pg_get_result() がコールされた場合、 それはブロックされます。

### パラメータ

`connection`
  PgSql\Connection クラスのインスタンス。

### 戻り値

接続がビジーの場合に `true` 、そうでない場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_reset

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_reset — 接続をリセット(再接続)する

### 説明

function pg_connection_reset(PgSql\Connection `$connection`): bool

pg_connection_reset() は接続をリセットします。 エラーからの復旧の際に有用です。

### パラメータ

`connection`
  PgSql\Connection クラスのインスタンス。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_connection_status — 接続ステータスを取得する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_consume_input

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_consume_input — 接続の入力を読み取る

### 説明

function pg_consume_input(PgSql\Connection `$connection`): bool

pg_consume_input() は、データベースサーバーからの 読み取りを待っているすべての入力を消費します。

### パラメータ

`connection`
  PgSql\Connection クラスのインスタンス。

### 戻り値

エラーが発生しなかった場合 `true`、 エラーがあった場合 `false`。 `true` が返されたからといって、入力が読み取り待機中であるとは限らないことに注意してください。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

# pg_convert

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_convert — 連想配列の値を、SQL 文として実行可能な形式に変換する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_copy_from

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_copy_from — 配列からテーブルに挿入する

### 説明

function pg_copy_from(
PgSql\Connection `$connection`,
string `$table_name`,
array|Traversable `$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` にコピーする iterable なデータ。 `rows` の個々の値が `table_name` のひとつの行となります。`rows` の個々の値は、 それぞれのフィールドに対応する値が区切り文字で区切られており、最後は 改行で終了していなければなりません。

`separator`

  `rows` の要素内で、各フィールドに対応する値を 区切る文字。デフォルトは `\t` です。

`null_as`

  `rows` の中で、SQL の `NULL` をどのように表現するか。デフォルトは `\\N` (`"\\\\N"`) です。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | `rows` の型が iterable になりました。 以前は、array でした。
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_to

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_copy_to — 配列にテーブルをコピーする

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_dbname

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_dbname — データベース名を取得する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
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_delete

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_delete — レコードを削除する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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 文として実行可能な形式に変換する

# pg_end_copy

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_end_copy — PostgreSQL バックエンドと同期する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
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 バックエンドに送信する

# pg_escape_bytea

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_escape_bytea — bytea フィールドに挿入するために文字列をエスケープする

### 説明

function pg_escape_bytea(PgSql\Connection `$connection` = ?, string `$string`): 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 以降では、デフォルトの接続を使うことは推奨されなくなりました。

`string`

  bytea 型のカラムに挿入するテキストまたはバイナリデータを含む 文字列。

### 戻り値

エスケープされたデータを文字列で返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_identifier

(PHP 5 >= 5.4.4, PHP 7, PHP 8)

pg_escape_identifier — テキスト型フィールドに挿入するために、識別子をエスケープする

### 説明

function pg_escape_identifier(PgSql\Connection `$connection` = ?, string `$string`): string|false

pg_escape_identifier() は、データベースへの問い合わせに使う識別子 (テーブル名やフィールド名など) をエスケープします。 PostgreSQL サーバー用にエスケープされた識別子を返します。 pg_escape_identifier() は、データの前後にダブルクォートを追加します。 ユーザーが自分で追加してはいけません。 この関数は、クエリ内で使う識別子のパラメータに有用です。SQL リテラル (bytea 以外のパラメータ) には、pg_escape_literal() あるいは pg_escape_string() を使わなければなりません。 bytea 型のフィールドには、pg_escape_bytea() を使わなければなりません。

### パラメータ

`connection`

  PgSql\Connection クラスのインスタンス。 `connection` が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

  警告

  PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

`string`

  エスケープするテキスト文字列。

### 戻り値

エスケープされたデータを文字列で返します。 失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_literal

(PHP 5 >= 5.4.4, PHP 7, PHP 8)

pg_escape_literal — テキスト型フィールドに挿入するために、リテラルをエスケープする

### 説明

function pg_escape_literal(PgSql\Connection `$connection` = ?, string `$string`): string|false

pg_escape_literal() は、 PostgreSQL データベースへの問い合わせに使うリテラルをエスケープします。 PostgreSQL フォーマットでエスケープされたリテラルを返します。 pg_escape_literal() は、データの前後にクォートを追加します。 ユーザーが自分で追加してはいけません。 pg_escape_string() ではなくこの関数を使うことを推奨します。 カラム型が bytea の場合は、代わりに pg_escape_bytea() を使わなければなりません。 識別子 (テーブル名やフィールド名など) のエスケープには pg_escape_identifier() を使わなければなりません。

### パラメータ

`connection`

  PgSql\Connection クラスのインスタンス。 `connection` が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

  警告

  PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

`string`

  エスケープするテキスト文字列。

### 戻り値

エスケープされたデータを文字列で返します。 失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_string

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_escape_string — クエリに使う文字列をエスケープする

### 説明

function pg_escape_string(PgSql\Connection `$connection` = ?, string `$string`): string

pg_escape_string() は、データベースへの問い合わせに使う文字列をエスケープします。 PostgreSQL フォーマットにエスケープされた文字列を、クォートなしの形式で返します。 PostgreSQL に使う SQL パラメータをエスケープするときには pg_escape_literal() を使うほうがよいでしょう。 addslashes() を PostgreSQL で使ってはいけません。 カラム型が bytea の場合は、代わりに pg_escape_bytea() を使わなければなりません。 識別子 (テーブル名やフィールド名など) のエスケープには pg_escape_identifier() を使わなければなりません。

### パラメータ

`connection`

  PgSql\Connection クラスのインスタンス。 `connection` が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

  警告

  PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

`string`

  エスケープするテキスト文字列。

### 戻り値

エスケープされたデータを文字列で返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_execute — 指定したパラメータを用いてプリペアドステートメントを実行するリクエストを 送信し、その結果を待つ

### 説明

function pg_execute(PgSql\Connection `$connection` = ?, string `$statement_name`, array `$params`): PgSql\Result|false

指定したパラメータを用いてプリペアドステートメントを実行するリクエストを 送信し、その結果を待ちます。

pg_execute() は pg_query_params() と似ています。しかし、実行するコマンドはクエリを指定することで 決まるのではなく、事前に準備されたステートメントに値を指定する ことによって決まります。この機能のおかげで、繰り返し使用される コマンドに構文解析や実行計画作成が最初の一度だけで済みます。 実行するステートメントは、カレントのセッションで事前に準備しておく 必要があります。

パラメータは pg_query_params() と同じですが、 クエリ文字列のかわりにプリペアドステートメントの名前を指定する という点だけが違います。

### パラメータ

`connection`

  PgSql\Connection クラスのインスタンス。 `connection` が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

  警告

  PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

`statement_name`

  実行するプリペアドステートメントの名前。"" が指定された場合は 無名ステートメントが実行されます。名前は、事前に pg_prepare()・pg_send_prepare() あるいは `PREPARE` SQL コマンドで準備されたものである 必要があります。

`params`

  プリペアドステートメント中の $1、$2 などのプレースホルダを 置き換えるパラメータの配列。配列の要素数はプレースホルダの 数と一致する必要があります。

  警告

  この関数をコールする際に、要素の内容は文字列に変換されます。

### 戻り値

成功した場合に PgSql\Result クラスのインスタンスを返します。 失敗した場合に `false` を返します.

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | PgSql\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_fetch_all

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_fetch_all — 取得されたすべての行を配列として取得する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
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_columns

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_fetch_all_columns — 指定したカラムの全ての行を配列として取得する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_array

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_fetch_array — 行を配列として取得する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_assoc

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_fetch_assoc — 行を連想配列として取得する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_object

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_fetch_object — 行をオブジェクトとして得る

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_fetch_result — 結果インスタンスから値を返す

### 説明

function pg_fetch_result(PgSql\Result `$result`, string|false|null `$row`, mixed `$field`): string|false|null
function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例1 pg_fetch_result() の例

    <?php
    $db = pg_connect("dbname=users user=me");

    $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_row

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_fetch_row — 数値添字の配列として行を得る

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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() - 結果インスタンスから値を返す

# pg_field_is_null

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_is_null — フィールドが SQL の `NULL` かどうか調べる

### 説明

function pg_field_is_null(PgSql\Result `$result`, string|false|null `$row`, mixed `$field`): int
function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_name

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_name — フィールドの名前を返す

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_num

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_num — 指定されたフィールドのフィールド番号を返す

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_prtlen

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_prtlen — 表示される長さを返す

### 説明

function pg_field_prtlen(PgSql\Result `$result`, string|false|null `$row`, mixed `$field_name_or_number`): int
function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_size

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_size — 指定したフィールドの内部記憶領域におけるサイズを返す

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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() - フィールド番号に対応する型名を返す

# pg_field_table

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

pg_field_table — tables フィールドの名前あるいは oid を返す

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_type

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_field_type — フィールド番号に対応する型名を返す

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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）を返す

# pg_field_type_oid

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_field_type_oid — フィールド番号に対応する型 ID（OID）を返す

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_flush

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_flush — 送信を待っているクエリデータをフラッシュする

### 説明

function pg_flush(PgSql\Connection `$connection`): int|bool

pg_flush() は、送信を待機中のすべての クエリデータを接続へフラッシュします。

### パラメータ

`connection`
  PgSql\Connection クラスのインスタンス。

### 戻り値

フラッシュが成功したか、またはフラッシュを待機中のデータがなかった場合 `true`、 保留中のデータの一部がフラッシュされたが、まだ残りがある場合、`0`。 失敗した場合に `false` を返します

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

# pg_free_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_free_result — クエリ結果のメモリを開放する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例1 pg_free_result() の例

    <?php
    $db = pg_connect("dbname=users user=me");

    $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() - 指定したパラメータを用いてプリペアドステートメントを実行するリクエストを 送信し、その結果を待つ
- pg_result_memory_size() - クエリーの結果に割り当てられたメモリ使用量を返す

# pg_get_notify

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_get_notify — SQL NOTIFY メッセージを取得する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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 を得る

# pg_get_pid

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_get_pid — バックエンドのプロセス ID を得る

### 説明

function pg_get_pid(PgSql\Connection `$connection`): int

pg_get_pid() は、バックエンド(データベースサーバー のプロセス)のプロセス ID を取得します。プロセス ID は、 `NOTIFY` メッセージが他のプロセスから送信されている かどうかを調べるために有用です。

### パラメータ

`connection`
  PgSql\Connection クラスのインスタンス。

### 戻り値

バックエンドのデータベースのプロセス ID 。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_result

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_get_result — 非同期クエリの結果を取得する

### 説明

function 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 クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_host

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_host — 接続に関連するホスト名を返す

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
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_insert

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_insert — テーブルに配列を挿入する

### 説明

function 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 クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_jit

(PHP 8 >= 8.4.0)

pg_jit — サーバーの JIT 情報を返す

### 説明

function pg_jit(?PgSql\Connection `$connection` = `null`): array

pg_jit() は、PostgreSQL サーバーの JIT (ジャストインタイムコンパイル) 情報を含む配列を返します。

### パラメータ

`connection`

  PgSql\Connection クラスのインスタンス。 `connection` が `null`, の場合、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

  警告

  PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

### 戻り値

サーバーの JIT 情報を含む array を返します。

### 参考

- pg_version() - クライアント・プロトコル・サーバーのバージョンを配列で返す

# pg_last_error

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_last_error — 特定の接続から直近のエラーメッセージ文字列を取得する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
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() - エラー報告の各フィールドを返す

# pg_last_notice

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

pg_last_notice — PostgreSQL サーバーからの直近の通知メッセージを返す

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
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() - 特定の接続から直近のエラーメッセージ文字列を取得する

# pg_last_oid

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_last_oid — 直近の行のオブジェクト ID を返す

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_lo_close

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_close — ラージオブジェクトをクローズする

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_create

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_create — ラージオブジェクトを生成する

### 説明

function pg_lo_create(PgSql\Connection `$connection` = ?, mixed `$object_id` = ?): int
function pg_lo_create(mixed `$object_id`): int

pg_lo_create() はラージオブジェクトを 生成し、そのラージオブジェクトの OID を返します。 PostgreSQL アクセスモード `INV_READ` および `INV_WRITE` はサポートされません。オブジェクトは 常に読み書き可のアクセス権で生成されます。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

ラージオブジェクトインターフェイス（アクセス制御もできないし使用が面倒） を使用するかわりに、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 を使用します。

### 戻り値

ラージオブジェクトの OID を返します。 失敗した場合に `false` を返します

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_export

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_export — ラージオブジェクトをファイルにエクスポートする

### 説明

function pg_lo_export(PgSql\Connection `$connection` = ?, int `$oid`, string `$filename`): bool

pg_lo_export() は PostgreSQL データベースから ラージオブジェクトを取得し、その内容をローカルファイルシステム上の ファイルに保存します。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

> 注意:

> この関数は、以前は pg_loexport() と呼ばれていました。

### パラメータ

`connection`

  PgSql\Connection クラスのインスタンス。 `connection` が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

  警告

  PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

`oid`

  データベース内のラージオブジェクトの OID 。

`filename`

  ラージオブジェクトをクライアントのファイルシステムに書き込む際の フルパスとファイル名。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_import

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_import — ファイルからラージオブジェクトをインポートする

### 説明

function pg_lo_import(PgSql\Connection `$connection` = ?, string `$filename`, int|string `$oid` = ?): int|string|false

pg_lo_import() は、ファイルシステム上のファイルの データをもとにして新しいラージオブジェクトをデータベース内に作成します。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

> 注意:

> この関数は、以前は pg_loimport() と呼ばれていました。

### パラメータ

`connection`

  PgSql\Connection クラスのインスタンス。 `connection` が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

  警告

  PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

`filename`

  クライアントのファイルシステムからラージオブジェクト用データを 読み込む際のフルパスとファイル名。

`oid`

  `oid` が指定されると、 この関数は指定された ID のラージオブジェクトを作成しようとします。 それ以外の場合は、サーバーから割り当てられたオブジェクト ID を使用します。 このパラメータは PostgreSQL 8.1 以降の新機能に依存しています。

### 戻り値

作成されたラージオブジェクトの OID を返します。 失敗した場合に `false` を返します

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_open

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_open — ラージオブジェクトをオープンする

### 説明

function 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 クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_read

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_read — ラージオブジェクトを読み込む

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_all

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_read_all — ラージオブジェクト全体を読み込みブラウザに直接送信する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_seek

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_seek — ラージオブジェクトの位置をシークする

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_tell

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_tell — ラージオブジェクトのカレントのシーク位置を返す

### 説明

function pg_lo_tell(PgSql\Lob `$lob`): int

pg_lo_tell() は、ラージオブジェクトのカレントの位置 （先頭からのオフセット）を返します。

ラージオブジェクトインターフェイスは、トランザクションブロックの中で 使用する必要があります。

### パラメータ

`lob`
  pg_lo_open() が返した PgSql\Lob クラスのインスタンス。

### 戻り値

ラージオブジェクトの先頭からのカレントのシーク位置（バイト数）を返します。 エラーが発生した場合は、負の数を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | `lob` は、PgSql\Lob クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_truncate

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_lo_truncate — ラージオブジェクトを切り詰める

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_unlink

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_unlink — ラージオブジェクトを削除する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_write

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_lo_write — ラージオブジェクトに書き込む

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
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_meta_data

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_meta_data — テーブルからメタデータを取得する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_num_fields

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_num_fields — フィールド数を返す

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_rows

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_num_rows — 行数を返す

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_options

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_options — 接続に関連するオプションを取得する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
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_parameter_status

(PHP 5, PHP 7, PHP 8)

pg_parameter_status — サーバーのパラメータ設定を検索する

### 説明

function pg_parameter_status(PgSql\Connection `$connection` = ?, string `$name`): string|false

サーバーのパラメータ設定を検索します。

いくつかのパラメータについては、接続の確立時や値の変更時にサーバーから 自動的に通知されます。pg_parameter_status() は これらの設定問い合わせるために使用可能です。指定したパラメータが存在する 場合にその値を、存在しない場合に `false` を返します。

サーバーから通知されるパラメータには以下が含まれます。 `server_version`、 `server_encoding`、`client_encoding`、 `is_superuser`、`session_authorization`、 `DateStyle`、`TimeZone` および `integer_datetimes`。 `server_version`、`server_encoding` および `integer_datetimes` は、PostgreSQL の稼動中には変更できないことに注意しましょう。

### パラメータ

`connection`

  PgSql\Connection クラスのインスタンス。 `connection` が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

  警告

  PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

`name`

  指定可能な `name` には以下が含まれます。 `server_version`、 `server_encoding`、`client_encoding`、 `is_superuser`、`session_authorization`、 `DateStyle`、`TimeZone` および `integer_datetimes`。 この値は、大文字小文字を区別するので注意して下さい。

### 戻り値

パラメータの値を文字列で返します。失敗した場合や `name` が間違っている場合には `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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

# pg_pconnect

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_pconnect — 持続的な PostgreSQL 接続をオープンする

### 説明

function 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 クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。

### 例

例1 pg_pconnect() の使用法

    <?php
    // "mary"という名前のデータベースに接続
    $dbconn = pg_pconnect("dbname=mary");

    // "localhost" のポート "5432" にて "mary" という名前のデータベースに接続
    $dbconn2 = pg_pconnect("host=localhost port=5432 dbname=mary");

    // ユーザー名とパスワードを指定してホスト"sheep"上の"mary"という名前のデータベースに接続
    $dbconn3 = pg_pconnect("host=sheep port=5432 dbname=mary user=lamb password=foo");

    // ユーザー名とパスワードを指定してホスト"sheep"上の"test"という名前のデータベースへ接続
    $conn_string = "host=sheep port=5432 dbname=test user=lamb password=bar";
    $dbconn4 = pg_pconnect($conn_string);
    ?>

### 参考

- pg_connect() - PostgreSQL 接続をオープンする
- 持続的データベース接続

# pg_ping

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_ping — データベース接続を調べる

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
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_port

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_port — 接続に関連するポート番号を返す

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
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_prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_prepare — 指定したパラメータでプリペアドステートメントを作成するリクエストを サーバーに送信し、その完了を待つ

### 説明

function pg_prepare(PgSql\Connection `$connection` = ?, string `$statement_name`, string `$query`): PgSql\Result|false

pg_prepare() は、 pg_execute() あるいは pg_send_execute() で後に実行するためのプリペアドステートメントを作成します。これにより、 繰り返し使用されるコマンドについての構文解析や実行計画作成が最初の 一度だけですみます。

この関数は `statement_name` という名前の プリペアドステートメントを `query` 文字列から作成します。 この文字列には 1 つの SQL コマンドが含まれている必要があります。 `statement_name` を `""` にすることで無名ステートメントを 作成することが可能で、既存の無名ステートメントは自動的に上書きされます。 それ以外の場合、もしカレントのセッションで既に定義済みのステートメント名を 使用した場合にはエラーとなります。パラメータを使用する際は、 `query` 内で `$1`、`$2` のような形式で参照されます。

pg_prepare() で使用するプリペアドステートメントは、 SQLの `PREPARE` 文を実行することでも作成可能です （しかし、パラメータの型を事前に指定する必要がないという点で pg_prepare() のほうがより柔軟です）。 また、PHP にはプリペアドステートメントを削除する関数がありませんが、 この目的のためには SQLの `DEALLOCATE` 文が使用可能です。

### パラメータ

`connection`

  PgSql\Connection クラスのインスタンス。 `connection` が指定されない場合は、デフォルトの接続を使います。 デフォルトの接続とは、pg_connect() または pg_pconnect() によって確立された直近の接続です。

  警告

  PHP 8.1.0 以降では、デフォルトの接続を使うことは推奨されなくなりました。

`statement_name`

  プリペアドステートメントにつける名前。接続内で一意である必要があります。 `""` が指定された場合は無名ステートメントが作成され、以前に定義された 無名ステートメントを上書きします。

`query`

  パラメータ化した SQL 文。ひとつの文のみである必要があります （複数の文をセミコロンで区切る形式は使用できません）。パラメータを 使用する際は `$1`、`$2` などの形式で参照されます。

### 戻り値

成功した場合に PgSql\Result クラスのインスタンスを返します。 失敗した場合に `false` を返します

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | PgSql\Result クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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() - 指定したパラメータでプリペアドステートメントを実行するリクエストを 送信し、その結果を待たない

# pg_put_copy_data

(PHP 8 >= 8.4.0)

pg_put_copy_data — COPY 操作中にサーバーへデータを送信する

### 説明

function pg_put_copy_data(PgSql\Connection `$connection`, string `$cmd`): int

`COPY FROM STDIN` 操作中に、サーバーへデータを送信します。 この関数を呼び出す前に、`COPY` コマンドを pg_query() で発行しておく必要があります。

### パラメータ

`connection`
  PgSql\Connection クラスのインスタンス。
`cmd`
  サーバーに送信するデータ。末尾に改行がない場合は、自動的に改行が付加されます。 データは、`COPY` コマンドのフォーマットに従って 整形されていなければなりません。

### 戻り値

成功した場合に `1` を、 データをキューに入れられなかった場合（ノンブロッキングモードのみ）に `0` を、エラーの場合に `-1` を返します。

### 参考

- pg_put_copy_end() - COPY 操作の完了をサーバーに通知する
- pg_query() - クエリを実行する

# pg_put_copy_end

(PHP 8 >= 8.4.0)

pg_put_copy_end — COPY 操作の完了をサーバーに通知する

### 説明

function pg_put_copy_end(PgSql\Connection `$connection`, ?string `$error` = `null`): int

`COPY FROM STDIN` 操作中に、 データの終端を示す通知をサーバーに送信します。

### パラメータ

`connection`
  PgSql\Connection クラスのインスタンス。
`error`
  `null` でない場合、`COPY` 操作は、 指定したエラーメッセージとともに強制的に失敗します。

### 戻り値

成功した場合に `1` を、 データをキューに入れられなかった場合（ノンブロッキングモードのみ）に `0` を、エラーの場合に `-1` を返します。

### 参考

- pg_put_copy_data() - COPY 操作中にサーバーへデータを送信する
- pg_query() - クエリを実行する

# pg_put_line

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_put_line — NULL で終わる文字列を PostgreSQL バックエンドに送信する

### 説明

function pg_put_line(PgSql\Connection `$connection` = ?, string `$query`): 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 以降では、デフォルトの接続を使うことは推奨されなくなりました。

`query`

  PostgreSQL バックエンドに直接送信されるテキストデータ。 最後に `NULL` が自動的に付加されます。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_query — クエリを実行する

### 説明

function 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 クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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() - 変更されたレコード(タプル)の数を返す

# pg_query_params

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_query_params — SQL コマンドとパラメータを分割してサーバーへ送信し、その結果を待つ

### 説明

function pg_query_params(PgSql\Connection `$connection` = ?, string `$query`, array `$params`): PgSql\Result|false

コマンドをサーバーに送信し、その結果を待ちます。パラメータを SQL コマンド とは別に渡すことが可能です。

pg_query_params() は pg_query() と似ていますが、追加の機能を有しています。それはパラメータ値が コマンド文字列と分離しているということです。

パラメータを使用する際は、`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 クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_result_error

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_result_error — 結果に関連するエラーメッセージを取得する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_field

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_result_error_field — エラー報告の各フィールドを返す

### 説明

function pg_result_error_field(PgSql\Result `$result`, int `$field_code`): string|false|null

pg_result_error_field() は、 `result` インスタンスに関するエラーメッセージの特定のフィールドを返します。 エラーフィールドは `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`、 `PGSQL_DIAG_INTERNAL_QUERY`、 `PGSQL_DIAG_CONTEXT`、`PGSQL_DIAG_SOURCE_FILE`、 `PGSQL_DIAG_SOURCE_LINE` あるいは `PGSQL_DIAG_SOURCE_FUNCTION` 。

### 戻り値

エラーフィールドの内容を文字列で返します。 フィールドが存在しない場合に `null` 、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | `result` は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_memory_size

(PHP 8 >= 8.4.0)

pg_result_memory_size — クエリーの結果に割り当てられたメモリ使用量を返す

### 説明

function pg_result_memory_size(PgSql\Result `$result`): int

指定されたクエリ結果 PgSql\Result インスタンスに割り当てられたメモリ使用量をバイト単位で返します。 この値は、 pg_free_result() によって解放されるメモリ使用量と同じです。

### パラメータ

`result`
  pg_query()、pg_query_params() や (様々な関数がありますが、特に) pg_execute() が返した PgSql\Result クラスのインスタンス。

### 戻り値

メモリ使用量をバイト単位で返します。

### 例

例1 pg_result_memory_size() の例

    <?php
    $db = pg_connect("dbname=users user=me");

    $res = pg_query($db, 'SELECT 1');

    $size = pg_result_memory_size($res);

    var_dump($size);
    ?>

上の例の出力は、 たとえば以下のようになります。

    int(3288)

### 参考

- pg_free_result() - クエリ結果のメモリを開放する

# pg_result_seek

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_result_seek — 結果インスタンスの内部行オフセットを設定する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_status

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_result_status — クエリ結果のステータスを取得する

### 説明

function 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_TUPLES_CHUNK`, `PGSQL_COPY_OUT`, `PGSQL_COPY_IN`, `PGSQL_BAD_RESPONSE`, `PGSQL_NONFATAL_ERROR`, `PGSQL_FATAL_ERROR`。 それ以外の場合は、PostgreSQL コマンドタグを含む文字列を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | `result` は、PgSql\Result クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_select

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_select — レコードを選択する

### 説明

function 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` のフィールド名をキーに、 取得対象となる行にマッチするデータを値にもつ配列。 PHP 8.4.0 以降は、空の配列を指定した場合には条件は適用されなくなっています。それより前のバージョンでは、`conditions` が空の場合は、関数そのものが失敗していました。

`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.4.0 | `conditions` は、オプションになりました。
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
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_send_execute

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_execute — 指定したパラメータでプリペアドステートメントを実行するリクエストを 送信し、その結果を待たない

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_prepare

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_prepare — 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その結果を待たない

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_query

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

pg_send_query — 非同期クエリを送信する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_params

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_send_query_params — コマンドとパラメータを分割してサーバーに送信し、その結果を待たない

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_set_chunked_rows_size

(PHP 8 >= 8.4.0)

pg_set_chunked_rows_size — チャンクモードで取得するクエリ結果の行数を設定する

### 説明

function pg_set_chunked_rows_size(PgSql\Connection `$connection`, int `$size`): bool

チャンクモードで取得するクエリ結果を設定します。 後に返されるクエリ結果は、最大`size` 行が含まれる複数のチャンクに分割されます。 この関数は、pg_get_result() を使って結果を取得する前にコールしなければいけません。 この関数は、libpq のバージョンが 17 以降の場合に利用可能です。

### パラメータ

`connection`
  PgSql\Connection クラスのインスタンス。
`size`
  チャンクごとに取得する行数

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### エラー / 例外

`size` が `1` より小さい場合、 ValueError がスローされます。

### 例

例1 pg_result_memory_size() の例

    <?php

    $conn = pg_connect($conn_str);

    for ($i = 0; $i < 10; $i ++) {
      pg_query($conn, "INSERT INTO users DEFAULT VALUES");
    }

    pg_send_query($conn, "SELECT * FROM users");
    pg_set_chunked_rows_size($conn, 1);

    $result = pg_get_result($conn);
    var_dump(pg_num_rows($result));

    // 結果を取得した以降に呼び出しても無意味
    var_dump(pg_set_chunked_rows_size($conn, 10));

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

    int(1)
    bool(false)

### 参考

- pg_get_result() - 非同期クエリの結果を取得する
- pg_result_status() - クエリ結果のステータスを取得する

# pg_set_client_encoding

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pg_set_client_encoding — クライアントのエンコーディングを設定する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_set_error_context_visibility

(PHP 8 >= 8.3.0)

pg_set_error_context_visibility — pg_last_error() が返すコンテクストのエラーメッセージのアクセス権を設定する

### 説明

function 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_set_error_verbosity

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_set_error_verbosity — pg_last_error() および pg_result_error() が返すメッセージの詳細度を指定する

### 説明

function pg_set_error_verbosity(PgSql\Connection `$connection` = ?, int `$verbosity`): int|false

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` のいずれかを返します。 失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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() - 結果に関連するエラーメッセージを取得する

# pg_socket

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

pg_socket — PostgreSQL 接続の下層にある、読み取り専用のソケットのハンドルを取得する

### 説明

function pg_socket(PgSql\Connection `$connection`): resource|false

pg_socket() は、 与えられた PostgreSQL 接続の下層にあるソケットに対応した、 読み取り専用の resource を返します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`connection`
  PgSql\Connection クラスのインスタンス。

### 戻り値

成功した場合は、ソケットのリソース。 失敗した場合に `false` を返します

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | `connection` は、PgSql\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

# pg_socket_poll

(PHP 8 >= 8.4.0)

pg_socket_poll — PostgreSQL 接続のソケットが読み取り/書き込み可能かどうかをポーリングする

### 説明

function pg_socket_poll(
resource `$socket`,
int `$read`,
int `$write`,
int `$timeout` = -1
): int

PostgreSQL 接続のソケットが読み取りおよび/または書き込み可能かどうかをポーリングします。 ソケットは pg_socket() を使って取得できます。 この関数は、ノンブロッキングな非同期クエリのワークフローを実装する際に役立ちます。

### パラメータ

`socket`
  pg_socket() から取得したソケットリソース。
`read`
  読み取り可能かをチェックするかどうか。 チェックする場合は `1` を、 スキップする場合は `0` を渡します。
`write`
  書き込み可能かをチェックするかどうか。 チェックする場合は `1` を、 スキップする場合は `0` を渡します。
`timeout`
  待機する最大のミリ秒数。 無期限に待機する場合は `-1` を、 まったく待機しない場合は `0` を渡します。

### 戻り値

ソケットの準備ができている場合は正の値を、 タイムアウトに達した場合は `0` を、 エラー時は `-1` を返します。

### 参考

- pg_socket() - PostgreSQL 接続の下層にある、読み取り専用のソケットのハンドルを取得する
- pg_consume_input() - 接続の入力を読み取る
- pg_send_query() - 非同期クエリを送信する

# pg_trace

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

pg_trace — PostgreSQL 接続のトレースを有効にする

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
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_transaction_status

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

pg_transaction_status — サーバー上で実行中のトランザクションの状態を返す

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

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

# pg_tty

(PHP 4, PHP 5, PHP 7, PHP 8)

pg_tty — 接続に関する TTY 名を返す

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
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;
    }
    ?>

# pg_unescape_bytea

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_unescape_bytea — bytea 型のバイナリをアンエスケープする

### 説明

function pg_unescape_bytea(string `$string`): string

pg_unescape_bytea() は、bytea 型のデータ文字列を アンエスケープし、エスケープしていない文字列、 場合によってはバイナリデータを返します。

> 注意:

> bytea 型を `SELECT` した場合、PostgreSQL は '\' で 始まる 8 進数のバイト値（例: \032）を返します。これをユーザーが手動で コンバートすることを期待されています。

### パラメータ

`string`

  PHP のバイナリ文字列に変換される PostgreSQL の bytea データを含む string。

### 戻り値

アンエスケープされたデータを文字列で返します。

### 例

例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() - クエリに使う文字列をエスケープする

# pg_untrace

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

pg_untrace — PostgreSQL 接続のトレースを無効にする

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
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_update

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

pg_update — テーブルを更新する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_version

(PHP 5, PHP 7, PHP 8)

pg_version — クライアント・プロトコル・サーバーのバージョンを配列で返す

### 説明

function pg_version(?PgSql\Connection `$connection` = `null`): array

pg_version() はクライアント・プロトコル およびサーバーのバージョンを配列で返します。

詳細なサーバー情報を取得するには 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
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() - サーバーのパラメータ設定を検索する

## 目次

- pg_affected_rows — 変更されたレコード(タプル)の数を返す
- pg_cancel_query — 非同期クエリを取り消す
- pg_change_password — PostgreSQL ユーザーのパスワードを変更する
- 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_jit — サーバーの JIT 情報を返す
- 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_copy_data — COPY 操作中にサーバーへデータを送信する
- pg_put_copy_end — COPY 操作の完了をサーバーに通知する
- pg_put_line — NULL で終わる文字列を PostgreSQL バックエンドに送信する
- pg_query — クエリを実行する
- pg_query_params — SQL コマンドとパラメータを分割してサーバーへ送信し、その結果を待つ
- pg_result_error — 結果に関連するエラーメッセージを取得する
- pg_result_error_field — エラー報告の各フィールドを返す
- pg_result_memory_size — クエリーの結果に割り当てられたメモリ使用量を返す
- pg_result_seek — 結果インスタンスの内部行オフセットを設定する
- pg_result_status — クエリ結果のステータスを取得する
- pg_select — レコードを選択する
- pg_send_execute — 指定したパラメータでプリペアドステートメントを実行するリクエストを 送信し、その結果を待たない
- pg_send_prepare — 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その結果を待たない
- pg_send_query — 非同期クエリを送信する
- pg_send_query_params — コマンドとパラメータを分割してサーバーに送信し、その結果を待たない
- pg_set_chunked_rows_size — チャンクモードで取得するクエリ結果の行数を設定する
- 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_socket_poll — PostgreSQL 接続のソケットが読み取り/書き込み可能かどうかをポーリングする
- pg_trace — PostgreSQL 接続のトレースを有効にする
- pg_transaction_status — サーバー上で実行中のトランザクションの状態を返す
- pg_tty — 接続に関する TTY 名を返す
- pg_unescape_bytea — bytea 型のバイナリをアンエスケープする
- pg_untrace — PostgreSQL 接続のトレースを無効にする
- pg_update — テーブルを更新する
- pg_version — クライアント・プロトコル・サーバーのバージョンを配列で返す

# PgSql\Connection クラス

(PHP 8 >= 8.1.0)

## はじめに

PHP 8.1.0 以降、`pgsql link` リソースを置き換える、完全不透明クラスです。

## クラス概要

namespace PgSql;
final class Connection {
}

# The PgSql\Result class

(PHP 8 >= 8.1.0)

## はじめに

PHP 8.1.0 以降、`pgsql result` リソースを置き換える、完全不透明クラスです。

## クラス概要

namespace PgSql;
final class Result {
}

# The PgSql\Lob class

(PHP 8 >= 8.1.0)

## はじめに

PHP 8.1.0 以降、`pgsql large object` リソースを置き換える、完全不透明クラスです。

## クラス概要

namespace PgSql;
final class Lob {
}

- インストール/設定
  - 要件
  - インストール手順
  - 実行時設定
  - リソース型
- 定義済み定数
- 例
  - 基本的な使用法
  - 基本的な使い方
- PostgreSQL 関数
  - pg_affected_rows — 変更されたレコード(タプル)の数を返す
  - pg_cancel_query — 非同期クエリを取り消す
  - pg_change_password — PostgreSQL ユーザーのパスワードを変更する
  - 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_jit — サーバーの JIT 情報を返す
  - 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_copy_data — COPY 操作中にサーバーへデータを送信する
  - pg_put_copy_end — COPY 操作の完了をサーバーに通知する
  - pg_put_line — NULL で終わる文字列を PostgreSQL バックエンドに送信する
  - pg_query — クエリを実行する
  - pg_query_params — SQL コマンドとパラメータを分割してサーバーへ送信し、その結果を待つ
  - pg_result_error — 結果に関連するエラーメッセージを取得する
  - pg_result_error_field — エラー報告の各フィールドを返す
  - pg_result_memory_size — クエリーの結果に割り当てられたメモリ使用量を返す
  - pg_result_seek — 結果インスタンスの内部行オフセットを設定する
  - pg_result_status — クエリ結果のステータスを取得する
  - pg_select — レコードを選択する
  - pg_send_execute — 指定したパラメータでプリペアドステートメントを実行するリクエストを 送信し、その結果を待たない
  - pg_send_prepare — 指定したパラメータでプリペアドステートメントを作成するリクエストを 送信し、その結果を待たない
  - pg_send_query — 非同期クエリを送信する
  - pg_send_query_params — コマンドとパラメータを分割してサーバーに送信し、その結果を待たない
  - pg_set_chunked_rows_size — チャンクモードで取得するクエリ結果の行数を設定する
  - 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_socket_poll — 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

# SQLite3

# はじめに

SQLite バージョン 3 のデータベースをサポートします。

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定

## 要件

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 function __construct(string `$filename`, int `$flags` = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string `$encryptionKey` = "")
public function backup(SQLite3 `$destination`, string `$sourceDatabase` = "main", string `$destinationDatabase` = "main"): bool
public function busyTimeout(int `$milliseconds`): bool
public function changes(): int
public function close(): bool
public function createAggregate(
string `$name`,
callable `$stepCallback`,
callable `$finalCallback`,
int `$argCount` = -1
): bool
public function createCollation(string `$name`, callable `$callback`): bool
public function createFunction(
string `$name`,
callable `$callback`,
int `$argCount` = -1,
int `$flags` = 0
): bool
public function enableExceptions(bool `$enable` = `false`): bool
public static function escapeString(string `$string`): string
public function exec(string `$query`): bool
public function lastErrorCode(): int
public function lastErrorMsg(): string
public function lastInsertRowID(): int
public function loadExtension(string `$name`): bool
public function open(string `$filename`, int `$flags` = SQLITE3_OPEN_READWRITE | SQLITE3_OPEN_CREATE, string `$encryptionKey` = ""): void
public function openBlob(
string `$table`,
string `$column`,
int `$rowid`,
string `$database` = "main",
int `$flags` = `SQLITE3_OPEN_READONLY`
): resource|false
public function prepare(string `$query`): SQLite3Stmt|false
public function query(string `$query`): SQLite3Result|false
public function querySingle(string `$query`, bool `$entireRow` = `false`): mixed
public function setAuthorizer(?callable `$callback`): bool
public static function 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

(PHP 7 >= 7.4.0, PHP 8)

SQLite3::backup — あるデータベースを、別のデータベースにバックアップする

### 説明

public function 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::busyTimeout

(PHP 5 >= 5.3.3, PHP 7, PHP 8)

SQLite3::busyTimeout — 接続がビジー状態のときのハンドラを設定する

### 説明

public function SQLite3::busyTimeout(int `$milliseconds`): bool

ビジーハンドラを設定します。 これは、データベースのロックが解除されるかあるいはタイムアウトに達するまでスリープさせます。

### パラメータ

`milliseconds`

  スリープさせる時間 (ミリ秒)。この値をゼロ以下にすると、 すでに設定されているタイムアウトハンドラを無効にします。

### 戻り値

成功した場合に `true`、失敗した場合に `false` を返します

# SQLite3::changes

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::changes — 直近の SQL 文で変更 (あるいは挿入、削除) された行の数を返す

### 説明

public function 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::close

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::close — データベースとの接続を閉じる

### 説明

public function SQLite3::close(): bool

データベースとの接続を閉じます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 例

例1 SQLite3::close() の例

    <?php
    $db = new SQLite3('mysqlitedb.db');
    $db->close();
    ?>

# SQLite3::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::__construct — SQLite3 オブジェクトを作成し、SQLite 3 データベースをオープンする

### 説明

public function 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());
    ?>

# SQLite3::createAggregate

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::createAggregate — SQL の集約関数として使用する PHP 関数を登録する

### 説明

public function SQLite3::createAggregate(
string `$name`,
callable `$stepCallback`,
callable `$finalCallback`,
int `$argCount` = -1
): bool

SQL の集約関数として使用する PHP 関数を登録します。 これは SQL 文の中で使用されるものです。

### パラメータ

`name`

  作成あるいは再定義したい SQL 集約関数の名前。

`stepCallback`

  結果セットの各行ごとにコールされるコールバック関数。 この関数で結果を集約し、集約処理のコンテキストに保存すべきです。

  このコールバック関数は、以下のように定義すべきです:

  function step(
  mixed `$context`,
  int `$rownumber`,
  mixed `$value`,
  mixed `...$values`
  ): mixed
  `context`

    最初の行では `null` です。 2行目以降は、step 関数から返された値をとります。 これは、集約の状況を管理するのに使います。

  `rownumber`

    現在の行番号

  `value`

    集約に渡されるはじめの引数

  `values`

    集約に渡されるふたつめ以降の引数

  この関数の戻り値は、 次のステップで呼ばれる際、または finalize 関数での `context` の引数として使われます。
`finalCallback`

  各行からの "段階的に処理された" データを集約するコールバック関数です。 いったん全データが処理されると、この関数が呼ばれます。 集約処理のコンテキストからデータを取り出し、結果を返すべきです。 このコールバック関数は SQLite が理解する型を返します。 (例: スカラー型)

  このコールバック関数は、以下のように定義すべきです:

  function 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() を使うことができます。

# SQLite3::createCollation

(PHP 5 >= 5.3.11, PHP 7, PHP 8)

SQLite3::createCollation — SQLのcollate関数として使うPHP関数を登録する

### 説明

public function SQLite3::createCollation(string `$name`, callable `$callback`): bool

SQL文の中でcollate関数として使うPHP関数、またはユーザー定義の関数を登録します。

### パラメータ

`name`

  作成、または再定義するSQL collate 関数の名前

`callback`

  collation の振る舞いを定義する、PHP関数または、 コールバックとして適用するユーザー定義関数。 2つの値を受けとり、strcmp() 関数が返すのと同じ値を返します。つまり、 はじめの文字列が前の文字列より前にソートされる場合に-1、 後にソートされる場合に1、等しい場合に0を返します。

  この関数は、以下のように定義されるべきです:

  function 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

# SQLite3::createFunction

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::createFunction — SQL のスカラー関数として使用する PHP 関数を登録する

### 説明

public function SQLite3::createFunction(
string `$name`,
callable `$callback`,
int `$argCount` = -1,
int `$flags` = 0
): bool

SQL のスカラー関数として使用する PHP 関数を登録します。 これは SQL 文の中で使用されるものです。

### パラメータ

`name`

  作成あるいは再定義したい SQL 関数の名前。

`callback`

  コールバックとして指定する、 PHP の関数あるいはユーザー定義関数の名前。 これが SQL 関数の振る舞いを定義します。

  この関数は、以下のように定義されるべきです:

  function 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::enableExceptions

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::enableExceptions — 例外のスローを有効にする

### 説明

public function 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::escapeString

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::escapeString — 適切にエスケープされた文字列を返す

### 説明

public static function SQLite3::escapeString(string `$string`): string

SQL 文の中で使えるよう適切にエスケープされた文字列を返します。

警告

この関数は (まだ)バイナリデータ対応ではありません!

BLOB フィールドには NUL 文字が含まれる可能性があります。BLOB フィールドを適切に処理するには、かわりに SQLite3Stmt::bindParam() を用いましょう。

### パラメータ

`string`

  エスケープしたい文字列。

### 戻り値

SQL 文の中で安全に使えるよう適切にエスケープされた文字列を返します。

### 注意

警告

SQLite クエリの文字列をクォートする際に addslashes() を使っては いけません。 予期せぬ結果を引き起こしてしまいます。

# SQLite3::exec

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::exec — 指定したデータベースに、結果を返さないクエリを実行する

### 説明

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

# SQLite3::lastErrorCode

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastErrorCode — 直近で失敗した SQLite リクエストの結果コードを数値で返す

### 説明

public function SQLite3::lastErrorCode(): int

直近で失敗した SQLite リクエストの結果コードを数値で返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

直近で失敗した SQLite リクエストの結果コードを数値で返します。

# SQLite3::lastErrorMsg

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastErrorMsg — 直近で失敗した SQLite リクエストについての英文テキストの説明を返す

### 説明

public function SQLite3::lastErrorMsg(): string

直近で失敗した SQLite リクエストについての英文テキストの説明を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

直近で失敗した SQLite リクエストについての英文テキストの説明を返します。

# SQLite3::lastInsertRowID

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::lastInsertRowID — 直近の INSERT 文でデータベースに追加された行の ID を返す

### 説明

public function SQLite3::lastInsertRowID(): int

直近の INSERT 文でデータベースに追加された行の ID を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

直近の INSERT 文でデータベースに追加された行の ID を返します。 現在の接続で、rowid テーブルへの INSERT が成功しなかったことがある場合は、 SQLite3::lastInsertRowID() は `0` を返します。

# SQLite3::loadExtension

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::loadExtension — SQLite 拡張ライブラリを読み込む

### 説明

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

# SQLite3::open

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::open — SQLite データベースをオープンする

### 説明

public function 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());
    ?>

# SQLite3::openBlob

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::openBlob — BLOB を読み取るためのストリームリソースを開く

### 説明

public function 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

# SQLite3::prepare

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::prepare — 実行する SQL 文を準備する

### 説明

public function 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() - パラメータを変数にバインドする

# SQLite3::query

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::query — SQL クエリを実行する

### 説明

public function 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::querySingle

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::querySingle — クエリを実行し、単一の結果を返す

### 説明

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

# SQLite3::setAuthorizer

(PHP 8)

SQLite3::setAuthorizer — SQL文が出来ることを限定するため、authorizer として使われるコールバックを設定する

### 説明

public function 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::version

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3::version — SQLite3 ライブラリのバージョンを、文字列定数と数値で返す

### 説明

public static function SQLite3::version(): array

SQLite3 ライブラリのバージョンを、文字列定数と数値で返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

キー "versionString" および "versionNumber" を持つ連想配列を返します。

### 例

例1 SQLite3::version() の例

    <?php
    print_r(SQLite3::version());
    ?>

上の例の出力は、 たとえば以下のようになります。

    Array
    (
        [versionString] => 3.5.9
        [versionNumber] => 3005009
    )

## 目次

- 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 クラス

(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 function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# SQLite3Stmt クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## はじめに

SQLite 3 拡張モジュールのプリペアドステートメントを扱うクラスです。

## クラス概要

class SQLite3Stmt {
/* メソッド */
private function __construct(SQLite3 `$sqlite3`, string `$query`)
public function bindParam(string|int `$param`, mixed `&$var`, int `$type` = `SQLITE3_TEXT`): bool
public function bindValue(string|int `$param`, mixed `$value`, int `$type` = `SQLITE3_TEXT`): bool
public function clear(): bool
public function close(): true
public function execute(): SQLite3Result|false
public function getSQL(bool `$expand` = `false`): string|false
public function paramCount(): int
public function readOnly(): bool
public function reset(): bool
}

# SQLite3Stmt::bindParam

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::bindParam — パラメータを変数にバインドする

### 説明

public function 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::bindValue

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::bindValue — パラメータの値を変数にバインドする

### 説明

public function 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::clear

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::clear — 現在バインドされているすべてのパラメータをクリアする

### 説明

public function SQLite3Stmt::clear(): bool

現在バインドされているすべてのパラメータをクリアします。 (それらを `null` に設定します)

警告

このメソッドは SQLite3Stmt::reset() と一緒に使う必要があります。 単独で使うと、 SQLite3Stmt::bindValue() や SQLite3Stmt::bindParam() の呼び出しが無意味になり、 全てのバインドされたパラメータが `null` になってしまいます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

バインドされているパラメータのクリアに成功した場合に `true`、 失敗した場合に `false` を返します。

# SQLite3Stmt::close

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::close — プリペアドステートメントを閉じる

### 説明

public function SQLite3Stmt::close(): true

プリペアドステートメントを閉じます。

> 注意: このプリペアドステートメントから取得したすべての SQLite3Result は、プリペアドステートメントを閉じた時点で無効になることに注意しましょう。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

常に `true` を返します。

### エラー / 例外

初期化されていないオブジェクト経由でこのメソッドを呼び出した場合、 Error がスローされます。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | オブジェクトが正しく初期化されていない場合、 このメソッドは Error をスローするようになりました。 これより前のバージョンでは、`false` を返していました。

# SQLite3Stmt::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::__construct — SQLite3Stmt オブジェクトを構築する

### 説明

private function SQLite3Stmt::__construct(SQLite3 `$sqlite3`, string `$query`)

SQLite3Stmt のインスタンスは、 SQLite3::prepare() によって作られます。

### パラメータ

`sqlite3`

`query`

# SQLite3Stmt::execute

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::execute — プリペアドステートメントを実行し、結果セットオブジェクトを返す

### 説明

public function SQLite3Stmt::execute(): SQLite3Result|false

プリペアドステートメントを実行し、結果セットオブジェクトを返します。

警告

同じステートメントオブジェクトに対して、 このメソッドを呼び出すことによって得られる結果セットは独立したものではありません。 むしろ、同じ基礎的な構造を共有しています。 よって、同じステートメントオブジェクトに対して SQLite3Stmt::execute() を再び呼ぶ前には、 SQLite3Result::finalize() を呼び出すことを推奨します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

プリペアドステートメントの実行に成功した場合に SQLite3Result オブジェクト、 失敗した場合に `false` を返します。

### 参考

- SQLite3::prepare() - 実行する SQL 文を準備する
- SQLite3Stmt::bindValue() - パラメータの値を変数にバインドする
- SQLite3Stmt::bindParam() - パラメータを変数にバインドする

# SQLite3Stmt::getSQL

(PHP 7 >= 7.4.0, PHP 8)

SQLite3Stmt::getSQL — ステートメントのSQLを取得する

### 説明

public function 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::paramCount

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::paramCount — プリペアドステートメント内のパラメータの数を返す

### 説明

public function SQLite3Stmt::paramCount(): int

プリペアドステートメント内のパラメータの数を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

プリペアドステートメント内のパラメータの数を返します。

### 参考

- SQLite3::prepare() - 実行する SQL 文を準備する

# SQLite3Stmt::readOnly

(PHP 5 >= 5.3.6, PHP 7, PHP 8)

SQLite3Stmt::readOnly — ステートメントが読み取り専用かどうかを返す

### 説明

public function SQLite3Stmt::readOnly(): bool

ステートメントが読み取り専用かどうかを返します。 ステートメントは、それが 直接 データベースファイルの内容を変更しなければ、読み取り専用と見なされます。 ユーザー定義のSQL関数は、間接的に 副作用としてデータベースを変更する可能性があることに注意してください。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

ステートメントが読み取り専用であれば `true` を返します。 そうでなければ `false` を返します。

# SQLite3Stmt::reset

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Stmt::reset — プリペアドステートメントをリセットする

### 説明

public function SQLite3Stmt::reset(): bool

プリペアドステートメントをリセットし、実行前の状態に戻します。 バインドした内容は、リセットしてもそのまま残ります。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

ステートメントのリセットに成功した場合に `true`、失敗した場合に `false` を返します

## 目次

- SQLite3Stmt::bindParam — パラメータを変数にバインドする
- SQLite3Stmt::bindValue — パラメータの値を変数にバインドする
- SQLite3Stmt::clear — 現在バインドされているすべてのパラメータをクリアする
- SQLite3Stmt::close — プリペアドステートメントを閉じる
- SQLite3Stmt::__construct — SQLite3Stmt オブジェクトを構築する
- SQLite3Stmt::execute — プリペアドステートメントを実行し、結果セットオブジェクトを返す
- SQLite3Stmt::getSQL — ステートメントのSQLを取得する
- SQLite3Stmt::paramCount — プリペアドステートメント内のパラメータの数を返す
- SQLite3Stmt::readOnly — ステートメントが読み取り専用かどうかを返す
- SQLite3Stmt::reset — プリペアドステートメントをリセットする

# SQLite3Result クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

## はじめに

SQLite 3 拡張モジュールの結果セットを扱うクラスです。

## クラス概要

class SQLite3Result {
/* メソッド */
private function __construct()
public function columnName(int `$column`): string|false
public function columnType(int `$column`): int|false
public function fetchArray(int `$mode` = `SQLITE3_BOTH`): array|false
public function finalize(): true
public function numColumns(): int
public function reset(): bool
}

# SQLite3Result::columnName

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::columnName — n 番目のカラムの名前を返す

### 説明

public function SQLite3Result::columnName(int `$column`): string|false

`column` で指定したカラムの名前を返します。 返されるカラムの名前は `AS` 句が指定された場合、そこで指定された値になります。 `AS` 句の指定がない場合、カラムの名前は不定となり、 libsqlite3 のリリースによって変わる可能性があります。

### パラメータ

`column`

  0 から始まるカラムの数値インデックス。

### 戻り値

`column` で指定したカラムの名前を文字列で返します。 カラムが存在しない場合は、`false` を返します。

# SQLite3Result::columnType

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::columnType — n 番目のカラムの型を返す

### 説明

public function SQLite3Result::columnType(int `$column`): int|false

`column` で指定したカラムの型を返します。

### パラメータ

`column`

  0 から始まるカラムの数値インデックス。

### 戻り値

`column` で指定したカラムのデータ型インデックス (`SQLITE3_INTEGER`、`SQLITE3_FLOAT`、 `SQLITE3_TEXT`、`SQLITE3_BLOB` あるいは `SQLITE3_NULL` のいずれか) を返します。 カラムが存在しない場合は、`false` を返します。

# SQLite3Result::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::__construct — SQLite3Result を構築する

### 説明

private function SQLite3Result::__construct()

SQLite3Result のインスタンスは、 SQLite3::query() と SQLite3Stmt::execute() によって作られます。

### パラメータ

この関数にはパラメータはありません。

# SQLite3Result::fetchArray

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::fetchArray — 結果の行を、連想配列あるいは数値添字配列あるいはその両方で取得する

### 説明

public function 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::finalize

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::finalize — 結果セットを閉じる

### 説明

public function SQLite3Result::finalize(): true

結果セットを閉じます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

常に `true` を返します。

### エラー / 例外

初期化されていないオブジェクト経由でこのメソッドを呼び出した場合、 Error がスローされます。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | オブジェクトが正しく初期化されていない場合、 このメソッドは Error をスローするようになりました。 これより前のバージョンでは、`false` を返していました。

# SQLite3Result::numColumns

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::numColumns — 結果セットのカラム数を返す

### 説明

public function SQLite3Result::numColumns(): int

結果セットのカラム数を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

結果セットのカラム数を返します。

# SQLite3Result::reset

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

SQLite3Result::reset — 結果セットを最初の行に戻す

### 説明

public function SQLite3Result::reset(): bool

結果セットを最初の行に戻します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

結果セットを最初の行に戻すことに成功した場合に `true`、 失敗した場合に `false` を返します。

## 目次

- SQLite3Result::columnName — n 番目のカラムの名前を返す
- SQLite3Result::columnType — n 番目のカラムの型を返す
- SQLite3Result::__construct — SQLite3Result を構築する
- SQLite3Result::fetchArray — 結果の行を、連想配列あるいは数値添字配列あるいはその両方で取得する
- SQLite3Result::finalize — 結果セットを閉じる
- SQLite3Result::numColumns — 結果セットのカラム数を返す
- SQLite3Result::reset — 結果セットを最初の行に戻す

- インストール/設定
  - 要件
  - インストール手順
  - 実行時設定
- 定義済み定数
- 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 — 結果セットを最初の行に戻す

# PHP 用 Microsoft SQL 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 からダウンロードできます。

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定
- リソース型

## 要件

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

(No version information available, might only be in Git)

sqlsrv_begin_transaction — Begins a database transaction

### 説明

function 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

# sqlsrv_cancel

(No version information available, might only be in Git)

sqlsrv_cancel — Cancels a statement

### 説明

function 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

# sqlsrv_client_info

(No version information available, might only be in Git)

sqlsrv_client_info — Returns information about the client and specified connection

### 説明

function 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

# sqlsrv_close

(No version information available, might only be in Git)

sqlsrv_close — Closes an open connection and releases resourses associated with the connection

### 説明

function 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

# sqlsrv_commit

(No version information available, might only be in Git)

sqlsrv_commit — Commits a transaction that was begun with sqlsrv_begin_transaction()

### 説明

function 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

# sqlsrv_configure

(No version information available, might only be in Git)

sqlsrv_configure — Changes the driver error handling and logging configurations

### 説明

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

# sqlsrv_connect

(No version information available, might only be in Git)

sqlsrv_connect — Opens a connection to a Microsoft SQL Server database

### 説明

function 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

# sqlsrv_errors

(No version information available, might only be in Git)

sqlsrv_errors — Returns error and warning information about the last SQLSRV operation performed

### 説明

function 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

# sqlsrv_execute

(No version information available, might only be in Git)

sqlsrv_execute — Executes a statement prepared with sqlsrv_prepare()

### 説明

function 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

# sqlsrv_fetch

(No version information available, might only be in Git)

sqlsrv_fetch — Makes the next row in a result set available for reading

### 説明

function 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_array

(No version information available, might only be in Git)

sqlsrv_fetch_array — 行を配列として返す

### 説明

function 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

# sqlsrv_fetch_object

(No version information available, might only be in Git)

sqlsrv_fetch_object — Retrieves the next row of data in a result set as an object

### 説明

function 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() - 行を配列として返す

# sqlsrv_field_metadata

(No version information available, might only be in Git)

sqlsrv_field_metadata — Retrieves metadata for the fields of a statement prepared by sqlsrv_prepare() or sqlsrv_query()

### 説明

function 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

# sqlsrv_free_stmt

(No version information available, might only be in Git)

sqlsrv_free_stmt — Frees all resources for the specified statement

### 説明

function 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

# sqlsrv_get_config

(No version information available, might only be in Git)

sqlsrv_get_config — Returns the value of the specified configuration setting

### 説明

function 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

# sqlsrv_get_field

(No version information available, might only be in Git)

sqlsrv_get_field — Gets field data from the currently selected row

### 説明

function 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

# sqlsrv_has_rows

(No version information available, might only be in Git)

sqlsrv_has_rows — Indicates whether the specified statement has rows

### 説明

function 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

# sqlsrv_next_result

(No version information available, might only be in Git)

sqlsrv_next_result — Makes the next result of the specified statement active

### 説明

function 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

# sqlsrv_num_fields

(No version information available, might only be in Git)

sqlsrv_num_fields — Retrieves the number of fields (columns) on a statement

### 説明

function 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

# sqlsrv_num_rows

(No version information available, might only be in Git)

sqlsrv_num_rows — Retrieves the number of rows in a result set

### 説明

function 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

# sqlsrv_prepare

(No version information available, might only be in Git)

sqlsrv_prepare — Prepares a query for execution

### 説明

function 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

# sqlsrv_query

(No version information available, might only be in Git)

sqlsrv_query — Prepares and executes a query

### 説明

function 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

# sqlsrv_rollback

(No version information available, might only be in Git)

sqlsrv_rollback — Rolls back a transaction that was begun with sqlsrv_begin_transaction()

### 説明

function 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

# sqlsrv_rows_affected

(No version information available, might only be in Git)

sqlsrv_rows_affected — Returns the number of rows modified by the last INSERT, UPDATE, or DELETE query executed

### 説明

function 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

# sqlsrv_send_stream_data

(No version information available, might only be in Git)

sqlsrv_send_stream_data — Sends data from parameter streams to the server

### 説明

function 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

# sqlsrv_server_info

(No version information available, might only be in Git)

sqlsrv_server_info — Returns information about the server

### 説明

function 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

## 目次

- 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 関数
  - 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

- 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 関数

- 抽象化レイヤー
  - 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 ドライバ

# 日付および時刻関連

# カレンダー

# はじめに

カレンダー拡張モジュールは異なったカレンダーフォーマット間の変換処理をシンプルにする関数の集まりです。標準としているのは、ユリウス積算日です。 ユリウス積算日は、紀元前 4713 年 1 月 1 日から数え始められています。 複数のカレンダーシステム間の変換を行うには、ユリウス積算日に変換した後 に選択したカレンダーシステムに変換しなければなりません。 ユリウス積算日はユリウス暦とはまったく異なります! ユリウス積算日の詳細を知りたいのであれば、 » http://www.hermetic.ch/cal_stud/jdn.htm を参照ください。 カレンダーシステムに関する情報を知りたいのであれば、 » http://www.fourmilab.ch/documents/calendar/ を参照ください。 本説明にはこのページからの引用が含まれています。 このページの内容はこのチュートリアルにも反映/引用されています。

# インストール/設定

## 目次

- インストール手順

## インストール手順

これらの関数を動作させるには、 --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

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_days_in_month — 指定した年とカレンダーについて、月の日数を返す

### 説明

function 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_from_jd

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_from_jd — ユリウス積算日からサポートされるカレンダーに変換する

### 説明

function 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_info

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_info — 特定のカレンダーに関する情報を返す

### 説明

function 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_to_jd

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cal_to_jd — サポートされるカレンダーからユリウス積算日に変換する

### 説明

function 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 タイムスタンプをユリウス歴に変換する

# easter_date

(PHP 4, PHP 5, PHP 7, PHP 8)

easter_date — 指定した年におけるローカルの復活祭の真夜中のUnix時を得る

### 説明

function 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 日から復活祭までの日数を得る を参照ください。

# easter_days

(PHP 4, PHP 5, PHP 7, PHP 8)

easter_days — 指定した年において、3 月 21 日から復活祭までの日数を得る

### 説明

function 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時を得る

# frenchtojd

(PHP 4, PHP 5, PHP 7, PHP 8)

frenchtojd — フランス革命暦をユリウス積算日に変換する

### 説明

function 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() - サポートされるカレンダーからユリウス積算日に変換する

# gregoriantojd

(PHP 4, PHP 5, PHP 7, PHP 8)

gregoriantojd — グレゴリウス日をユリウス積算日に変換する

### 説明

function 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() - サポートされるカレンダーからユリウス積算日に変換する

# jddayofweek

(PHP 4, PHP 5, PHP 7, PHP 8)

jddayofweek — 曜日を返す

### 説明

function jddayofweek(int `$julian_day`, int `$mode` = `CAL_DOW_DAYNO`): int|string

曜日を返します。 モードに依存した文字あるいは整数を返す事が出来ます。

### パラメータ

`julian_day`

  ユリウス積算日を表す整数値。

`mode`

  暦の曜日モード
  モード | 意味
  --- | ---
  0 (デフォルト) | 整数で曜日番号 (0=Sunday, 1=Monday, 等)を返します。
  1 | 曜日(英グレゴリウス)を含む文字列を返します。
  2 | 曜日の省略形(英グレゴリウス)を含む文字列を返します。

### 戻り値

グレゴリウス暦の曜日を表す数値あるいは文字列を返します。

# jdmonthname

(PHP 4, PHP 5, PHP 7, PHP 8)

jdmonthname — 月の名前を返す

### 説明

function 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

### パラメータ

`julian_day`

  変換したいユリウス積算日。

`mode`

  カレンダーのモード(上の表を参照)

### 戻り値

指定したユリウス積算日と `mode` にもとづく月名を返します。

# jdtofrench

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtofrench — ユリウス積算日をフランス革命暦(共和暦)に変換する

### 説明

function jdtofrench(int `$julian_day`): string

ユリウス積算日をフランス革命暦に変換します。

### パラメータ

`julian_day`

  ユリウス積算日を表す整数値。

### 戻り値

フランス革命暦の日付を "月/日/年" 形式の文字列で返します。

### 参考

- frenchtojd() - フランス革命暦をユリウス積算日に変換する
- cal_from_jd() - ユリウス積算日からサポートされるカレンダーに変換する

# jdtogregorian

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtogregorian — ユリウス積算日をグレゴリウス日に変換する

### 説明

function jdtogregorian(int `$julian_day`): string

ユリウス積算日を "月/日/年" の形式でグレゴリウス日を含む文字列に変換します。

### パラメータ

`julian_day`

  ユリウス積算日を表す整数値。

### 戻り値

グレゴリウス暦の日付を "月/日/年" 形式の文字列で返します。

### 参考

- gregoriantojd() - グレゴリウス日をユリウス積算日に変換する
- cal_from_jd() - ユリウス積算日からサポートされるカレンダーに変換する

# jdtojewish

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtojewish — ユリウス積算日をユダヤ暦に変換する

### 説明

function 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() - ユリウス積算日からサポートされるカレンダーに変換する

# jdtojulian

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtojulian — ユリウス積算日をユリウス暦に変換する

### 説明

function jdtojulian(int `$julian_day`): string

ユリウス積算日を "月/日/年" の形式でユリウス暦を含む文字列に変換します。

### パラメータ

`julian_day`

  ユリウス積算日を表す整数値。

### 戻り値

ユリウス暦の日付を "月/日/年" 形式の文字列で返します。

### 参考

- juliantojd() - ユリウス暦をユリウス積算日に変換する
- cal_from_jd() - ユリウス積算日からサポートされるカレンダーに変換する

# jdtounix

(PHP 4, PHP 5, PHP 7, PHP 8)

jdtounix — ユリウス歴を Unix タイムスタンプに変換する

### 説明

function 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 タイムスタンプをユリウス歴に変換する

# jewishtojd

(PHP 4, PHP 5, PHP 7, PHP 8)

jewishtojd — ユダヤ暦の日付けをユリウス積算日に変換する

### 説明

function 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() - サポートされるカレンダーからユリウス積算日に変換する

# juliantojd

(PHP 4, PHP 5, PHP 7, PHP 8)

juliantojd — ユリウス暦をユリウス積算日に変換する

### 説明

function 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() - サポートされるカレンダーからユリウス積算日に変換する

# unixtojd

(PHP 4, PHP 5, PHP 7, PHP 8)

unixtojd — Unix タイムスタンプをユリウス歴に変換する

### 説明

function unixtojd(?int `$timestamp` = `null`): int|false

Unix タイムスタンプ(1970/1/1 からの秒数)`timestamp` をユリウス歴に変換して返します。`timestamp` が 指定されない場合は現在の日付が使用されます。 どちらの場合でも、時刻は地方時間と見なされます(UTCではありません)。

### パラメータ

`timestamp`

  変換したい Unix タイムスタンプ。

### 戻り値

ユリウス積算日を表す整数値を返します。 失敗した場合に `false` を返します

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `timestamp` は、nullable になりました。

### 参考

- jdtounix() - ユリウス歴を Unix タイムスタンプに変換する

## 目次

- cal_days_in_month — 指定した年とカレンダーについて、月の日数を返す
- cal_from_jd — ユリウス積算日からサポートされるカレンダーに変換する
- cal_info — 特定のカレンダーに関する情報を返す
- cal_to_jd — サポートされるカレンダーからユリウス積算日に変換する
- easter_date — 指定した年におけるローカルの復活祭の真夜中のUnix時を得る
- easter_days — 指定した年において、3 月 21 日から復活祭までの日数を得る
- frenchtojd — フランス革命暦をユリウス積算日に変換する
- gregoriantojd — グレゴリウス日をユリウス積算日に変換する
- jddayofweek — 曜日を返す
- jdmonthname — 月の名前を返す
- jdtofrench — ユリウス積算日をフランス革命暦(共和暦)に変換する
- jdtogregorian — ユリウス積算日をグレゴリウス日に変換する
- jdtojewish — ユリウス積算日をユダヤ暦に変換する
- jdtojulian — ユリウス積算日をユリウス暦に変換する
- jdtounix — ユリウス歴を Unix タイムスタンプに変換する
- jewishtojd — ユダヤ暦の日付けをユリウス積算日に変換する
- juliantojd — ユリウス暦をユリウス積算日に変換する
- unixtojd — Unix タイムスタンプをユリウス歴に変換する

- インストール/設定
  - インストール手順
- 定義済み定数
- カレンダー 関数
  - 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 タイムスタンプをユリウス歴に変換する

# 日付・時刻

# はじめに

DateTimeImmutable と、 それに関連するクラスを使うと、日付/時刻 に関する情報を表現できます。 このオブジェクトは、日付/時刻 の文字列表現か、 現在のシステム時刻から作成できます。

この情報を変更したり、 フォーマット化するために豊富なメソッドが提供されています。 この情報には、タイムゾーンや夏時間の遷移情報も含まれます。

PHP の日付/時刻 は ISO 8601 のカレンダー、つまり » proleptic Gregorian calendar (先発グレゴリオ暦) を実装しています。 これは、現在のうるう年のルールをグレゴリオ暦より前であっても実装し、 `-1 BCE` と `1 CE` の間を `0` 年として扱います。 うるう秒はサポートされていません。

日付と時刻の情報は内部的には 64 ビット数値で保持されているので、 (負の年も含めて) 考え得る限りのあらゆる日付を扱うことができます。 扱える範囲は、過去およそ2920億年と未来の同じくらいの年です。

> 注意: この節で参照しているタイムゾーンは、 サポートされるタイムゾーンのリスト で見つけられます。

# インストール/設定

## 目次

- インストール手順
- 実行時設定

## インストール手順

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() など）で使用します。

`returnFormat` は date_sunrise() と date_sunset() で利用可能です。
警告

これらの定数は PHP 8.4.0 から非推奨となりました。 対応する date_sunrise() と date_sunset() 関数は PHP 8.1.0 から非推奨となっています。

`SUNFUNCS_RET_TIMESTAMP` (int)
  タイムスタンプ
`SUNFUNCS_RET_STRING` (int)
  時:分 (例: `08:02`)
`SUNFUNCS_RET_DOUBLE` (int)
  時刻を表す浮動小数点値 (例 `8.75`)

`DATE_*` 定数
`DATE_ATOM` (string)
  Atom (例: `2005-08-15T15:52:01+00:00`)。ISO-8601, RFC 3339, XML Schema と互換性があります
`DATE_COOKIE` (string)
  HTTP Cookies (例: `Monday, 15-Aug-2005 15:52:01 UTC`)
`DATE_ISO8601` (string)
  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` (string)
  ISO-8601 拡張形式 (例: `+10191-07-26T08:59:52+01:00`)

  > 注意: 年に常に符号を含めることで、ISO-8601 の通常の範囲 `0000`-`9999` 以外の値が許されています。 タイムゾーンの部分 (`+01:00`) については、 ISO-8601 と互換性をとるようにもなっています。

`DATE_RFC822` (string)
  RFC 822 (例: `Mon, 15 Aug 05 15:52:01 +0000`)
`DATE_RFC850` (string)
  RFC 850 (例: `Monday, 15-Aug-05 15:52:01 UTC`)
`DATE_RFC1036` (string)
  RFC 1036 (例: `Mon, 15 Aug 05 15:52:01 +0000`)
`DATE_RFC1123` (string)
  RFC 1123 (例: `Mon, 15 Aug 2005 15:52:01 +0000`)
`DATE_RFC7231` (string)
  RFC 7231 (PHP 7.0.19 and 7.1.5 以降で利用可能) (例: `Sat, 30 Apr 2016 17:52:13 GMT`)
`DATE_RFC2822` (string)
  RFC 2822 (例: `Mon, 15 Aug 2005 15:52:01 +0000`)
`DATE_RFC3339` (string)
  `DATE_ATOM` と同じです
`DATE_RFC3339_EXTENDED` (string)
  RFC 3339 EXTENDED フォーマット (例: `2005-08-15T15:52:01.000+00:00`)
`DATE_RSS` (string)
  RSS (例: `Mon, 15 Aug 2005 15:52:01 +0000`). `DATE_RFC1123` のエイリアス.
`DATE_W3C` (string)
  World Wide Web Consortium (例: `2005-08-15T15:52:01+00:00`) `DATE_RFC3339` のエイリアス

# 例

## 目次

- 日付/時刻 の算術

## 日付/時刻 の算術

以下の例は、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 function __construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)
public function add(DateInterval `$interval`): DateTime
public static function createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTime|false
public static function createFromImmutable(DateTimeImmutable `$object`): static
public static function createFromInterface(DateTimeInterface `$object`): DateTime
public static function createFromTimestamp(int|float `$timestamp`): static
public function modify(string `$modifier`): DateTime
public static function __set_state(array `$array`): DateTime
public function setDate(int `$year`, int `$month`, int `$day`): DateTime
public function setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTime
public function setMicrosecond(int `$microsecond`): static
public function setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTime
public function setTimestamp(int `$timestamp`): DateTime
public function setTimezone(DateTimeZone `$timezone`): DateTime
public function sub(DateInterval `$interval`): DateTime
public function diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function format(string `$format`): string
public function getMicrosecond(): int
public function getOffset(): int
public function getTimestamp(): int
public function getTimezone(): DateTimeZone|false
public function __serialize(): array
public function __unserialize(array `$data`): void
#[\Deprecated]
public function __wakeup(): void
}

## 変更履歴

バージョン | 説明
--- | ---
8.4.0 | クラス定数が型付けされました。
7.2.0 | DateTime クラスの定数は、 DateTimeInterface で定義されるようになりました。
7.1.0 | DateTime のコンストラクタで構築される値に、 現在時刻のマイクロ秒が含まれるようになりました。 これより前のバージョンでは、このマイクロ秒の情報は常に `0` で初期化されていました。

# DateTime::add

# date_add

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::add -- date_add — 年月日時分秒の値を加えることで、DateTime オブジェクトを変更する

### 説明

オブジェクト指向型

public function DateTime::add(DateInterval `$interval`): DateTime

手続き型

function date_add(DateTime `$object`, DateInterval `$interval`): DateTime

指定した DateInterval オブジェクトを、 指定した DateTime オブジェクトに加えます。

DateTimeImmutable::add() と似ていますが、 DateTime オブジェクトを使って動作します。

手続き型のバージョンは、 DateTime を最初の引数に取ります。

### パラメータ

`object`
  手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。
`interval`

  DateInterval オブジェクト

### 戻り値

メソッドチェインに使う、変更された DateTime オブジェクトを返します。

### 参考

- DateTimeImmutable::add() - 年月日時分秒の値を加え、新しいオブジェクトを返す

# DateTime::__construct

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::__construct — 新しい DateTime オブジェクトを返す

### 説明

public function 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::createFromFormat

# date_create_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::createFromFormat -- date_create_from_format — 指定した書式で時刻文字列をパースする

### 説明

オブジェクト指向型

public static function DateTime::createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTime|false

手続き型

function 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() - 時刻の文字列を指定されたフォーマットに従ってパースする

# DateTime::createFromImmutable

(PHP 7 >= 7.3.0, PHP 8)

DateTime::createFromImmutable — 与えられた DateTimeImmutable オブジェクトをカプセル化した、新しい DateTime のインスタンスを返す

### 説明

public static function 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 );

# DateTime::createFromInterface

(PHP 8)

DateTime::createFromInterface — 指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTime オブジェクトを返す

### 説明

public static function 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);

# DateTime::createFromTimestamp

(PHP 8 >= 8.4.0)

DateTime::createFromTimestamp — Unix タイムスタンプからインスタンスを生成する

### 説明

public static function DateTime::createFromTimestamp(int|float `$timestamp`): static

Unix タイムスタンプからインスタンスを生成します。

### パラメータ

`timestamp`
  日付を表す Unix タイムスタンプ。 float の値も受け付けるため、マイクロ秒の精度を指定できます。

### 戻り値

新しい DateTime インスタンスを返します。

### エラー / 例外

`timestamp` が [`PHP_INT_MIN`, `PHP_INT_MAX`] の範囲外の場合、DateRangeError がスローされます。

### 例

例1 DateTime::createFromTimestamp() の例

    <?php
    $date = DateTime::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u');
    ?>

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

    1970-01-01 00:02:03.456789

# DateTime::getLastErrors

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::getLastErrors — DateTimeImmutable::getLastErrors() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 DateTimeImmutable::getLastErrors()

# DateTime::modify

# date_modify

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::modify -- date_modify — タイムスタンプを変更する

### 説明

オブジェクト指向型

public function DateTime::modify(string `$modifier`): DateTime

手続き型

function date_modify(DateTime `$object`, string `$modifier`): DateTime|false

DateTimeImmutable::__construct() 形式で加算あるいは減算することによって DateTime オブジェクトのタイムスタンプを変更します。

### パラメータ

`object`
  手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。
`modifier`

  日付/時刻 文字列。有効な書式については 日付と時刻の書式 で説明しています。

### 戻り値

成功した場合は DateTime を返します。 手続き型 の場合は、失敗したときに `false` を返します。

### エラー / 例外

オブジェクト指向のAPIのみ、 無効な日付/時刻の文字列が渡された場合に DateMalformedStringException がスローされます。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 仮の戻り値の型が、DateTime になりました。 これより前のバージョンでは、 DateTime|false でした。
8.3.0 | 無効な文字列が渡された場合、 DateTime::modify() は DateMalformedStringException をスローするようになりました。 これより前のバージョンでは、 警告が発生して `false` を返していました。 date_modify() は変更されていません。

### 例

例1 DateTime::modify() の例

オブジェクト指向型

    <?php
    $date = new DateTime('2006-12-12');
    $date->modify('+1 day');
    echo $date->format('Y-m-d');

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

    2006-12-13

手続き型

    <?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 タイムスタンプを用いて日付と時刻を設定する

# DateTime::__set_state

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::__set_state — __set_state ハンドラ

### 説明

public static function DateTime::__set_state(array `$array`): DateTime

__set_state() ハンドラを処理します。

DateTimeImmutable::__set_state() に似ていますが、 DateTime を使って動作します。

### パラメータ

`array`

  初期化配列。

### 戻り値

新しい DateTime オブジェクトのインスタンスを返します。

# DateTime::setDate

# date_date_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setDate -- date_date_set — 日付を設定する

### 説明

オブジェクト指向型

public function DateTime::setDate(int `$year`, int `$month`, int `$day`): DateTime

手続き型

function 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() - 日付を設定する

# DateTime::setISODate

# date_isodate_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setISODate -- date_isodate_set — ISO 形式の日付を設定する

### 説明

オブジェクト指向型

public function DateTime::setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTime

手続き型

function 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::setMicrosecond

(PHP 8 >= 8.4.0)

DateTime::setMicrosecond — 時刻のマイクロ秒部分を設定する

### 説明

public function DateTime::setMicrosecond(int `$microsecond`): static

時刻のマイクロ秒部分を設定します。

DateTimeImmutable::setMicrosecond() に似ていますが、 DateTime を使って動作します。

### パラメータ

`microsecond`
  設定するマイクロ秒の値 (`0` から `999999`)。

### 戻り値

メソッドチェインに使う、変更された DateTime オブジェクトを返します。

### エラー / 例外

`microsecond` が [`0`, `999999`] の範囲外の場合、 DateRangeError がスローされます。

### 例

例1 DateTime::setMicrosecond() の例

    <?php
    $date = DateTime::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u') . PHP_EOL;
    $date->setMicrosecond(987654);
    echo $date->format('Y-m-d H:i:s.u') . PHP_EOL;
    ?>

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

    1970-01-01 00:02:03.456789
    1970-01-01 00:02:03.987654

### 参考

- DateTimeInterface::getMicrosecond() - Unix タイムスタンプのマイクロ秒部分を取得する

# DateTime::setTime

# date_time_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setTime -- date_time_set — 時刻を設定する

### 説明

オブジェクト指向型

public function DateTime::setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTime

手続き型

function 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() - 時刻を設定する

# DateTime::setTimestamp

# date_timestamp_set

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::setTimestamp -- date_timestamp_set — Unix タイムスタンプを用いて日付と時刻を設定する

### 説明

オブジェクト指向型

public function DateTime::setTimestamp(int `$timestamp`): DateTime

手続き型

function date_timestamp_set(DateTime `$object`, int `$timestamp`): DateTime

Unix タイムスタンプを用いて日付と時刻を設定します。

DateTimeImmutable::setTimestamp() に似ていますが、 DateTime を使って動作します。

手続き型のバージョンは、 DateTime オブジェクトを最初の引数に取ります。

### パラメータ

`object`
  手続き型のみ: date_create() が返す DateTime オブジェクト。 この関数は、このオブジェクトを変更します。
`timestamp`

  日付を表す Unix タイムスタンプ。 DateTimeImmutable::modify() を `@` フォーマットと共に使うと、 int の範囲外のタイムスタンプを設定できます。

### 戻り値

メソッドチェインに使う、変更された DateTime オブジェクトを返します。

### 参考

- DateTimeImmutable::setTimestamp() - Unix タイムスタンプを用いて日付と時刻を設定する
- DateTime::setMicrosecond() - 時刻のマイクロ秒部分を設定する

# DateTime::setTimezone

# date_timezone_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTime::setTimezone -- date_timezone_set — DateTime オブジェクトのタイムゾーンを設定する

### 説明

オブジェクト指向型

public function DateTime::setTimezone(DateTimeZone `$timezone`): DateTime

手続き型

function 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";

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

    2000-01-01 00:00:00+12:00
    2000-01-01 01:45:00+13:45

手続き型

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

# date_sub

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::sub -- date_sub — 年月日時分秒の値を DateTime オブジェクトから引く

### 説明

オブジェクト指向型

public function DateTime::sub(DateInterval `$interval`): DateTime

手続き型

function 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() - 年月日時分秒の値を引く

## 目次

- DateTime::add — 年月日時分秒の値を加えることで、DateTime オブジェクトを変更する
- DateTime::__construct — 新しい DateTime オブジェクトを返す
- DateTime::createFromFormat — 指定した書式で時刻文字列をパースする
- DateTime::createFromImmutable — 与えられた DateTimeImmutable オブジェクトをカプセル化した、新しい DateTime のインスタンスを返す
- DateTime::createFromInterface — 指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTime オブジェクトを返す
- DateTime::createFromTimestamp — Unix タイムスタンプからインスタンスを生成する
- DateTime::getLastErrors — DateTimeImmutable::getLastErrors のエイリアス
- DateTime::modify — タイムスタンプを変更する
- DateTime::__set_state — __set_state ハンドラ
- DateTime::setDate — 日付を設定する
- DateTime::setISODate — ISO 形式の日付を設定する
- DateTime::setMicrosecond — 時刻のマイクロ秒部分を設定する
- DateTime::setTime — 時刻を設定する
- DateTime::setTimestamp — Unix タイムスタンプを用いて日付と時刻を設定する
- DateTime::setTimezone — DateTime オブジェクトのタイムゾーンを設定する
- DateTime::sub — 年月日時分秒の値を DateTime オブジェクトから引く

# 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 function __construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)
#[\NoDiscard(message: "as DateTimeImmutable::add() does not modify the object itself")]
public function add(DateInterval `$interval`): DateTimeImmutable
public static function createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false
public static function createFromInterface(DateTimeInterface `$object`): DateTimeImmutable
public static function createFromMutable(DateTime `$object`): static
public static function createFromTimestamp(int|float `$timestamp`): static
public static function getLastErrors(): array|false
#[\NoDiscard(message: "as DateTimeImmutable::modify() does not modify the object itself")]
public function modify(string `$modifier`): DateTimeImmutable
public static function __set_state(array `$array`): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setDate() does not modify the object itself")]
public function setDate(int `$year`, int `$month`, int `$day`): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setISODate() does not modify the object itself")]
public function setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setMicrosecond() does not modify the object itself")]
public function setMicrosecond(int `$microsecond`): static
#[\NoDiscard(message: "as DateTimeImmutable::setTime() does not modify the object itself")]
public function setTime(
int `$hour`,
int `$minute`,
int `$second` = 0,
int `$microsecond` = 0
): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setTimestamp() does not modify the object itself")]
public function setTimestamp(int `$timestamp`): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::setTimezone() does not modify the object itself")]
public function setTimezone(DateTimeZone `$timezone`): DateTimeImmutable
#[\NoDiscard(message: "as DateTimeImmutable::sub() does not modify the object itself")]
public function sub(DateInterval `$interval`): DateTimeImmutable
public function diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function format(string `$format`): string
public function getMicrosecond(): int
public function getOffset(): int
public function getTimestamp(): int
public function getTimezone(): DateTimeZone|false
public function __serialize(): array
public function __unserialize(array `$data`): void
#[\Deprecated]
public function __wakeup(): void
}

## 変更履歴

バージョン | 説明
--- | ---
8.4.0 | クラス定数が型付けされました。
7.1.0 | DateTimeImmutable のコンストラクタで構築される値に、 現在時刻のマイクロ秒が含まれるようになりました。 これより前のバージョンでは、このマイクロ秒の情報は常に `0` で初期化されていました。

# DateTimeImmutable::add

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::add — 年月日時分秒の値を加え、新しいオブジェクトを返す

### 説明

#[\NoDiscard(message: "as DateTimeImmutable::add() does not modify the object itself")]
public function 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::__construct

# date_create_immutable

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::__construct -- date_create_immutable — 新しい DateTimeImmutable オブジェクトを返す

### 説明

オブジェクト指向型

public function DateTimeImmutable::__construct(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`)

手続き型

function 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');

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

    2000-01-01

手続き型

    <?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_default_timezone_set('America/Jamaica');

    // 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";

    // PHP のデフォルトのタイムゾーンでの現在日時
    $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

> 注意:

> 繰り上がった日付は、 DateTimeImmutable::getLastErrors() の警告をチェックすることで検知できます。

例3 関連付けられたタイムゾーンを変更する

    <?php
    $timeZone = new \DateTimeZone('Asia/Tokyo');

    $time = new \DateTimeImmutable();
    $time = $time->setTimezone($timeZone);

    echo $time->format('Y/m/d H:i:s e'), "\n";

上の例の出力は、 たとえば以下のようになります。

    2022/08/12 23:49:23 Asia/Tokyo

例4 相対日付/時刻 の文字列を使う

    <?php
    $time = new \DateTimeImmutable("-1 year");

    echo $time->format('Y/m/d H:i:s'), "\n";

上の例の出力は、 たとえば以下のようになります。

    2021/08/12 15:43:51

# 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 function DateTimeImmutable::createFromFormat(string `$format`, string `$datetime`, ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

手続き型

function 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 桁までの数値で表した年 | 例: `25` (`0025` と同じ), `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`。 タイムゾーンについてはデフォルトのタイムゾーン) にリセットします。 | `!` がなければ、すべてのフィールドは現在の日時に設定されます。
  `|` | まだパースされていないすべてのフィールド (年、月、日、時、分、秒、マイクロ秒およびタイムゾーン情報) を ゼロ相当の値にリセットします。 | `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'
    );
    echo $date->format('c e') . "\n";

    $date = DateTimeImmutable::createFromFormat(
        DateTimeInterface::RFC3339_EXTENDED,
        '2013-10-14T09:00:00.000+02:00'
    );
    echo $date->format('c e') . "\n";

この例で使われている 定義済みの定数 は、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 が生成した日付/時刻をパースする

# DateTimeImmutable::createFromInterface

(PHP 8)

DateTimeImmutable::createFromInterface — 指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTimeImmutable オブジェクトを返す

### 説明

public static function 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);

# DateTimeImmutable::createFromMutable

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

DateTimeImmutable::createFromMutable — 与えられた DateTime オブジェクトをカプセル化した、新しいDateTimeImmutable のインスタンスを返す

### 説明

public static function 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::createFromTimestamp

(PHP 8 >= 8.4.0)

DateTimeImmutable::createFromTimestamp — Unix タイムスタンプからインスタンスを生成する

### 説明

public static function DateTimeImmutable::createFromTimestamp(int|float `$timestamp`): static

Unix タイムスタンプからインスタンスを生成します。

### パラメータ

`timestamp`
  日付を表す Unix タイムスタンプ。 float の値も受け付けるため、マイクロ秒の精度を指定できます。

### 戻り値

新しい DateTimeImmutable インスタンスを返します。

### エラー / 例外

`timestamp` が [`PHP_INT_MIN`, `PHP_INT_MAX`] の範囲外の場合、 DateRangeError がスローされます。

### 例

例1 DateTimeImmutable::createFromTimestamp() の例

    <?php
    $date = DateTimeImmutable::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u');
    ?>

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

    1970-01-01 00:02:03.456789

# DateTimeImmutable::getLastErrors

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::getLastErrors — 警告およびエラーを返す

### 説明

public static function 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
            )
    )
    Failed to parse time string (asdfasdf) at position 0 (a): The timezone could not be found in the database

この出力のインデックス 6 と 0 は、エラーが発生した文字列内での文字の位置を表します。

例2 繰り上がった日付を検知する

    <?php
    $date = DateTimeImmutable::createFromFormat('!Y-m-d', '2020-02-30');
    print_r(DateTimeImmutable::getLastErrors());

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

    Array
    (
        [warning_count] => 1
        [warnings] => Array
            (
                [10] => The parsed date was invalid
            )

        [error_count] => 0
        [errors] => Array
            (
            )
    )

# DateTimeImmutable::modify

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::modify — タイムスタンプを変更した新しいオブジェクトを作る

### 説明

#[\NoDiscard(message: "as DateTimeImmutable::modify() does not modify the object itself")]
public function DateTimeImmutable::modify(string `$modifier`): DateTimeImmutable

タイムスタンプを変更した新しい DateTimeImmutable オブジェクトを作ります。 元のオブジェクトは変更されません。

### パラメータ

`modifier`

  日付/時刻 文字列。有効な書式については 日付と時刻の書式 で説明しています。

### 戻り値

成功時に DateTimeImmutable を返します。 手続き型 の場合は、失敗したときに `false` を返します。

### エラー / 例外

無効な日付/時刻の文字列が渡された場合、 DateMalformedStringException がスローされます。 PHP 8.3.0 より前のバージョンでは、警告が発生していました。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 仮の戻り値の型が、DateTimeImmutable になりました。 これより前のバージョンでは、 DateTimeImmutable|false でした。
8.3.0 | 無効な文字列が渡された場合、 DateTimeImmutable::modify() は DateMalformedStringException をスローするようになりました。 これより前のバージョンでは、 警告が発生して `false` を返していました。

### 例

例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 タイムスタンプを用いて日付と時刻を設定する

# DateTimeImmutable::__set_state

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::__set_state — __set_state ハンドラ

### 説明

public static function DateTimeImmutable::__set_state(array `$array`): DateTimeImmutable

__set_state() ハンドラを処理します。

### パラメータ

`array`

  初期化配列。

### 戻り値

新しい DateTimeImmutable オブジェクトのインスタンスを返します。

# DateTimeImmutable::setDate

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setDate — 日付を設定する

### 説明

#[\NoDiscard(message: "as DateTimeImmutable::setDate() does not modify the object itself")]
public function 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() - 時刻を設定する

# DateTimeImmutable::setISODate

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setISODate — ISO 日付を設定する

### 説明

#[\NoDiscard(message: "as DateTimeImmutable::setISODate() does not modify the object itself")]
public function DateTimeImmutable::setISODate(int `$year`, int `$week`, int `$dayOfWeek` = 1): DateTimeImmutable

ISO 8601 標準形式、 つまり特定の日付ではなく、週と日のオフセットで日付を設定した、 新しい DateTimeImmutable オブジェクトを返します。

### パラメータ

`year`

  その日付の年。

`week`

  その日付の週。

`dayOfWeek`

  週の最初の日からのオフセット。

### 戻り値

変更されたデータを持つ、新しい DateTimeImmutable オブジェクトを返します。

### 例

例1 DateTimeImmutable::setISODate() の例

オブジェクト指向型

    <?php

    $date = new DateTimeImmutable();

    $newDate = $date->setISODate(2008, 2);
    echo $newDate->format('Y-m-d') . "\n";

    $newDate = $date->setISODate(2008, 2, 7);
    echo $newDate->format('Y-m-d') . "\n";

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

    2008-01-07
    2008-01-13

手続き型

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

(PHP 8 >= 8.4.0)

DateTimeImmutable::setMicrosecond — 時刻のマイクロ秒部分を設定する

### 説明

#[\NoDiscard(message: "as DateTimeImmutable::setMicrosecond() does not modify the object itself")]
public function DateTimeImmutable::setMicrosecond(int `$microsecond`): static

元のオブジェクトを基にマイクロ秒部分を変更した、 新しい DateTimeImmutable オブジェクトを返します。

### パラメータ

`microsecond`
  設定するマイクロ秒の値 (`0` から `999999`)。

### 戻り値

変更されたデータを持つ、新しい DateTimeImmutable オブジェクトを返します。

### エラー / 例外

`microsecond` が [`0`, `999999`] の範囲外の場合、DateRangeError がスローされます。

### 例

例1 DateTimeImmutable::setMicrosecond() の例

    <?php
    $date = DateTimeImmutable::createFromTimestamp(123.456789);
    echo $date->format('Y-m-d H:i:s.u') . PHP_EOL;
    $date = $date->setMicrosecond(987654);
    echo $date->format('Y-m-d H:i:s.u') . PHP_EOL;
    ?>

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

    1970-01-01 00:02:03.456789
    1970-01-01 00:02:03.987654

### 参考

- DateTimeInterface::getMicrosecond() - Unix タイムスタンプのマイクロ秒部分を取得する

# DateTimeImmutable::setTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTime — 時刻を設定する

### 説明

#[\NoDiscard(message: "as DateTimeImmutable::setTime() does not modify the object itself")]
public function 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 日付を設定する

# DateTimeImmutable::setTimestamp

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTimestamp — Unix タイムスタンプを用いて日付と時刻を設定する

### 説明

#[\NoDiscard(message: "as DateTimeImmutable::setTimestamp() does not modify the object itself")]
public function DateTimeImmutable::setTimestamp(int `$timestamp`): DateTimeImmutable

Unix タイムスタンプを用いて日付と時刻を設定し、 古いものから新しい DateTimeImmutable オブジェクトを作成して返します。

### パラメータ

`timestamp`

  日付を表す Unix タイムスタンプ。 DateTimeImmutable::modify() を `@` フォーマットと共に使うと、 int の範囲外のタイムスタンプを設定できます。

### 戻り値

変更されたデータを持つ、新しい 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::setMicrosecond() - 時刻のマイクロ秒部分を設定する

# DateTimeImmutable::setTimezone

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::setTimezone — タイムゾーンを設定する

### 説明

#[\NoDiscard(message: "as DateTimeImmutable::setTimezone() does not modify the object itself")]
public function 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::sub

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

DateTimeImmutable::sub — 年月日時分秒の値を引く

### 説明

#[\NoDiscard(message: "as DateTimeImmutable::sub() does not modify the object itself")]
public function 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() - タイムスタンプを変更した新しいオブジェクトを作る

## 目次

- DateTimeImmutable::add — 年月日時分秒の値を加え、新しいオブジェクトを返す
- DateTimeImmutable::__construct — 新しい DateTimeImmutable オブジェクトを返す
- DateTimeImmutable::createFromFormat — 時刻の文字列を指定されたフォーマットに従ってパースする
- DateTimeImmutable::createFromInterface — 指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTimeImmutable オブジェクトを返す
- DateTimeImmutable::createFromMutable — 与えられた DateTime オブジェクトをカプセル化した、新しいDateTimeImmutable のインスタンスを返す
- DateTimeImmutable::createFromTimestamp — Unix タイムスタンプからインスタンスを生成する
- DateTimeImmutable::getLastErrors — 警告およびエラーを返す
- DateTimeImmutable::modify — タイムスタンプを変更した新しいオブジェクトを作る
- DateTimeImmutable::__set_state — __set_state ハンドラ
- DateTimeImmutable::setDate — 日付を設定する
- DateTimeImmutable::setISODate — ISO 日付を設定する
- DateTimeImmutable::setMicrosecond — 時刻のマイクロ秒部分を設定する
- DateTimeImmutable::setTime — 時刻を設定する
- DateTimeImmutable::setTimestamp — Unix タイムスタンプを用いて日付と時刻を設定する
- DateTimeImmutable::setTimezone — タイムゾーンを設定する
- DateTimeImmutable::sub — 年月日時分秒の値を引く

# 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 function diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function format(string `$format`): string
public function getMicrosecond(): int
public function getOffset(): int
public function getTimestamp(): int
public function getTimezone(): DateTimeZone|false
public function __serialize(): array
public function __unserialize(array `$data`): void
#[\Deprecated]
public function __wakeup(): void
}

## 定義済み定数

`DateTimeInterface::ATOM` string
`DATE_ATOM`
  Atom (例: 2005-08-15T15:52:01+00:00)。ISO-8601、RFC 3339、および XML Schema と互換性があります
`DateTimeInterface::COOKIE` string
`DATE_COOKIE`
  HTTP Cookie (例: Monday, 15-Aug-2005 15:52:01 UTC)
`DateTimeInterface::ISO8601` string
`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` string
`DATE_ISO8601_EXPANDED`
  ISO-8601 拡張形式 (例: +10191-07-26T08:59:52+01:00)

  > 注意: 年に常に符号を含めることで、ISO-8601 の通常の範囲 `0000`-`9999` 以外の値が許されています。 タイムゾーンの部分 (`+01:00`) については、 ISO-8601 と互換性を保証するようにもなっています。

`DateTimeInterface::RFC822` string
`DATE_RFC822`
  RFC 822 (例: Mon, 15 Aug 05 15:52:01 +0000)
`DateTimeInterface::RFC850` string
`DATE_RFC850`
  RFC 850 (例: Monday, 15-Aug-05 15:52:01 UTC)
`DateTimeInterface::RFC1036` string
`DATE_RFC1036`
  RFC 1036 (例: Mon, 15 Aug 05 15:52:01 +0000)
`DateTimeInterface::RFC1123` string
`DATE_RFC1123`
  RFC 1123 (例: Mon, 15 Aug 2005 15:52:01 +0000)
`DateTimeInterface::RFC7231` string
`DATE_RFC7231`
  RFC 7231 (PHP 7.0.19 と 7.1.5以降) (例: Sat, 30 Apr 2016 17:52:13 GMT)
`DateTimeInterface::RFC2822` string
`DATE_RFC2822`
  RFC 2822 (例: Mon, 15 Aug 2005 15:52:01 +0000)
`DateTimeInterface::RFC3339` string
`DATE_RFC3339`
  `DATE_ATOM` と同じです
`DateTimeInterface::RFC3339_EXTENDED` string
`DATE_RFC3339_EXTENDED`
  RFC 3339 EXTENDED フォーマット (例: 2005-08-15T15:52:01.000+00:00)
`DateTimeInterface::RSS` string
`DATE_RSS`
  RSS (例: Mon, 15 Aug 2005 15:52:01 +0000)
`DateTimeInterface::W3C` string
`DATE_W3C`
  World Wide Web Consortium (例: 2005-08-15T15:52:01+00:00)

## 変更履歴

バージョン | 説明
--- | ---
8.5.0 | 定数 `DATE_RFC7231` および `DateTimeInterface::RFC7231` は、推奨されなくなりました。
8.4.0 | クラス定数が型付けされました。
8.2.0 | 定数 `DateTimeInterface::ISO8601_EXPANDED` が追加されました。
7.2.0 | DateTime クラスの定数は、 DateTimeInterface で定義されるようになりました。

# 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 function DateTimeInterface::diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function DateTimeImmutable::diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval
public function DateTime::diff(DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval

手続き型

function date_diff(DateTimeInterface `$baseObject`, DateTimeInterface `$targetObject`, bool `$absolute` = `false`): DateInterval

ふたつの DateTime オブジェクトの差を返します。

### パラメータ

`datetime`

  比較する日付。

`absolute`

  間隔が正の数になるようにするか否か。

### 戻り値

ふたつの日付の差をあらわす DateInterval オブジェクトを返します。

`absolute` は、 DateInterval オブジェクトの `invert` プロパティにのみ影響します。

さらに厳密に言うと、戻り値はもともとのオブジェクト (`$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');

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

    +2 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");
    $targetTime = new DateTimeImmutable("2021-10-31 08:30:00 Europe/London");
    $interval = $originalTime->diff($targetTime);
    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");
    $targetTime = new DateTimeImmutable("2023-12-31 UTC");
    $interval = $originalTime->diff($targetTime);
    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::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 function DateTimeInterface::format(string `$format`): string
public function DateTimeImmutable::format(string `$format`): string
public function DateTime::format(string `$format`): string

手続き型

function 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 型だからです。 一方 DateTimeInterface 型のオブジェクトをマイクロ秒つきで作成した場合は、 DateTimeInterface::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 日付。拡張されていないフォーマット(9999年まで)とだけ、互換性があります。それより未来の日付は無効な文字列になります。そうした日付と拡張フォーマットについては、`x` と `X` を参照ください。 | 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');
    ?>

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

    2000-01-01 00:00:00

手続き型

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

# DateTimeImmutable::getMicrosecond

# DateTime::getMicrosecond

(PHP 8 >= 8.4.0)

DateTimeInterface::getMicrosecond -- DateTimeImmutable::getMicrosecond -- DateTime::getMicrosecond — Unix タイムスタンプのマイクロ秒部分を取得する

### 説明

public function DateTimeInterface::getMicrosecond(): int
public function DateTimeImmutable::getMicrosecond(): int
public function DateTime::getMicrosecond(): int

Unix タイムスタンプのマイクロ秒部分を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

その日付をあらわす Unix タイムスタンプのマイクロ秒部分を返します。

### 例

例1 DateTimeInterface::getMicrosecond() の例

    <?php
    $date = new DateTimeImmutable('2024-01-01 12:34:56.789123');
    var_dump($date->format('u'));
    var_dump($date->getMicrosecond());
    ?>

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

    string(6) "789123"
    int(789123)

### 参考

- DateTimeInterface::getTimestamp() - Unix タイムスタンプを取得する
- DateTimeInterface::format() - 指定した書式でフォーマットした日付を返す

# 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 function DateTimeInterface::getOffset(): int
public function DateTimeImmutable::getOffset(): int
public function DateTime::getOffset(): int

手続き型

function 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";

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

    -18000
    -14400

手続き型

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

# 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 function DateTimeInterface::getTimestamp(): int
public function DateTimeImmutable::getTimestamp(): int
public function DateTime::getTimestamp(): int

手続き型

function date_timestamp_get(DateTimeInterface `$object`): int

Unix タイムスタンプを取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

その日付をあらわす Unix タイムスタンプを返します。

### エラー / 例外

タイムスタンプが int として表現できない場合、 DateRangeError がスローされます。 PHP 8.3.0 より前のバージョンでは、ValueError がスローされていました。また、PHP 8.0.0 より前のバージョンでは同様の場合に `false` を返していました。 それでも、DateTimeInterface::format() に `U` を指定すると、タイムスタンプは string として取得できます。

### 変更履歴

バージョン | 説明
--- | ---
8.3.0 | 範囲外の例外が DateRangeError になりました。
8.0.0 | これらの関数は、失敗時に `false` を返さなくなりました。

### 例

例1 DateTime::getTimestamp() の例

オブジェクト指向型

    <?php
    $date = new DateTimeImmutable();
    echo $date->getTimestamp();

上の例の出力は、 たとえば以下のようになります。

    1272509157

手続き型

    <?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() - 指定した書式でフォーマットした日付を返す
- DateTimeInterface::getMicrosecond() - Unix タイムスタンプのマイクロ秒部分を取得する

# 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 function DateTimeInterface::getTimezone(): DateTimeZone|false
public function DateTimeImmutable::getTimezone(): DateTimeZone|false
public function DateTime::getTimezone(): DateTimeZone|false

手続き型

function date_timezone_get(DateTimeInterface `$object`): DateTimeZone|false

指定した DateTime に関連するタイムゾーンを返します。

### パラメータ

`object`
  手続き型のみ: date_create() が返す DateTime オブジェクト

### 戻り値

成功した場合に DateTimeZone オブジェクト、失敗した場合に `false` を返します。

### 例

例1 DateTime::getTimezone() の例

オブジェクト指向型

    <?php
    $date = new DateTimeImmutable("now", new DateTimeZone('Europe/London'));
    $tz = $date->getTimezone();
    echo $tz->getName();

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

    Europe/London

手続き型

    <?php
    $date = date_create("now", timezone_open('Europe/London'));
    $tz = date_timezone_get($date);
    echo timezone_name_get($tz);

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

    Europe/London

### 参考

- DateTime::setTimezone() - DateTime オブジェクトのタイムゾーンを設定する

# DateTime::__serialize

# DateTimeImmutable::__serialize

# DateTimeInterface::__serialize

(PHP 8 >= 8.2.0)

DateTime::__serialize -- DateTimeImmutable::__serialize -- DateTimeInterface::__serialize — DateTime をシリアライズする

### 説明

public function DateTime::__serialize(): array
public function DateTimeImmutable::__serialize(): array
public function DateTimeInterface::__serialize(): array

The __serialize() handler.

### パラメータ

この関数にはパラメータはありません。

### 戻り値

DateTime の シリアライズ表現を返します。

### 例

例1 DateTime::serialize() の例

    <?php
    $date = new DateTime('2025-03-27');
    var_dump(serialize($date));

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

    string(114) "O:8:"DateTime":3:{s:4:"date";s:26:"2025-03-27 00:00:00.000000";s:13:"timezone_type";i:3;s:8:"timezone";s:3:"UTC";}"

### 参考

- DateTime::__unserialize() - Datetime をアンシリアライズする

# DateTime::__unserialize

# DateTimeImmutable::__unserialize

# DateTimeInterface::__unserialize

(PHP 8 >= 8.2.0)

DateTime::__unserialize -- DateTimeImmutable::__unserialize -- DateTimeInterface::__unserialize — Datetime をアンシリアライズする

### 説明

public function DateTime::__unserialize(array `$data`): void
public function DateTimeImmutable::__unserialize(array `$data`): void
public function DateTimeInterface::__unserialize(array `$data`): void

__unserialize() ハンドラです。

### パラメータ

`data`

  シリアライズされた DateTime

### 戻り値

DateTime オブジェクトを返します。

### 例

例1 DateTime::unserialize() の例

    <?php
    $serializedDate = 'O:8:"DateTime":3:{s:4:"date";s:26:"2025-03-27 00:00:00.000000";s:13:"timezone_type";i:3;s:8:"timezone";s:3:"UTC";}';
    var_dump(unserialize($serializedDate));

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

    object(DateTime)#1 (3) {
      ["date"]=>
      string(26) "2025-03-27 00:00:00.000000"
      ["timezone_type"]=>
      int(3)
      ["timezone"]=>
      string(3) "UTC"
    }

### 参考

- DateTime::__serialize() - DateTime をシリアライズする

# DateTime::__wakeup

# DateTimeImmutable::__wakeup

# DateTimeInterface::__wakeup

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTime::__wakeup -- DateTimeImmutable::__wakeup -- DateTimeInterface::__wakeup — __wakeup ハンドラ

警告

この関数は PHP 8.5.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
public function DateTime::__wakeup(): void
#[\Deprecated]
public function DateTimeImmutable::__wakeup(): void
#[\Deprecated]
public function DateTimeInterface::__wakeup(): void

__wakeup() を処理します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

DateTime オブジェクトを初期化します。

## 目次

- DateTimeInterface::diff — ふたつの DateTime オブジェクトの差を返す
- DateTimeInterface::format — 指定した書式でフォーマットした日付を返す
- DateTimeInterface::getMicrosecond — Unix タイムスタンプのマイクロ秒部分を取得する
- DateTimeInterface::getOffset — タイムゾーンのオフセットを返す
- DateTimeInterface::getTimestamp — Unix タイムスタンプを取得する
- DateTimeInterface::getTimezone — 指定した DateTime に関連するタイムゾーンを返す
- DateTime::__serialize — DateTime をシリアライズする
- DateTime::__unserialize — Datetime をアンシリアライズする
- DateTime::__wakeup — __wakeup ハンドラ

# 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 function __construct(string `$timezone`)
public function getLocation(): array|false
public function getName(): string
public function getOffset(DateTimeInterface `$datetime`): int
public function getTransitions(int `$timestampBegin` = `PHP_INT_MIN`, int `$timestampEnd` = 2147483647): array|false
public static function listAbbreviations(): array
public static function listIdentifiers(int `$timezoneGroup` = `DateTimeZone::ALL`, ?string `$countryCode` = `null`): array
}

## 定義済み定数

`DateTimeZone::AFRICA` int

  アフリカのタイムゾーン。

`DateTimeZone::AMERICA` int

  アメリカのタイムゾーン。

`DateTimeZone::ANTARCTICA` int

  南極のタイムゾーン。

`DateTimeZone::ARCTIC` int

  北極のタイムゾーン。

`DateTimeZone::ASIA` int

  アジアのタイムゾーン。

`DateTimeZone::ATLANTIC` int

  大西洋のタイムゾーン。

`DateTimeZone::AUSTRALIA` int

  オーストラリアのタイムゾーン。

`DateTimeZone::EUROPE` int

  ヨーロッパのタイムゾーン。

`DateTimeZone::INDIAN` int

  インドのタイムゾーン。

`DateTimeZone::PACIFIC` int

  太平洋のタイムゾーン。

`DateTimeZone::UTC` int

  UTC タイムゾーン。

`DateTimeZone::ALL` int

  すべてのタイムゾーン。

`DateTimeZone::ALL_WITH_BC` int

  過去との互換性を保つものを含むすべてのタイムゾーン。

`DateTimeZone::PER_COUNTRY` int

  国ごとのタイムゾーン。

## 変更履歴

バージョン | 説明
--- | ---
8.4.0 | クラス定数が型付けされました。

# DateTimeZone::__construct

# timezone_open

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::__construct -- timezone_open — 新しい DateTimeZone オブジェクトを作成する

### 説明

オブジェクト指向型

public function DateTimeZone::__construct(string `$timezone`)

手続き型

function 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);
            echo $mars->getName() . "\n";
        } catch(Exception $e) {
            echo $e->getMessage() . "\n";
        }
    }

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

    Europe/London
    DateTimeZone::__construct() [datetimezone.--construct]: Unknown or bad timezone (Mars/Phobos)
    DateTimeZone::__construct() [datetimezone.--construct]: Unknown or bad timezone (Jupiter/Europa)

# DateTimeZone::getLocation

# timezone_location_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateTimeZone::getLocation -- timezone_location_get — タイムゾーンの位置情報を返す

### 説明

オブジェクト指向型

public function DateTimeZone::getLocation(): array|false

手続き型

function timezone_location_get(DateTimeZone `$object`): array|false

タイムゾーンの位置情報 (国コード、緯度/経度、コメント) を返します。

### パラメータ

`object`
  手続き型のみ: timezone_open() が返す DateTimeZone オブジェクト

### 戻り値

タイムゾーンについての位置情報を含む配列を返します。失敗した場合に `false` を返します

### 例

例1 DateTimeZone::getLocation() の例

    <?php
    $tz = new DateTimeZone("Asia/Jakarta");
    print_r($tz->getLocation());
    print_r(timezone_location_get($tz));

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

    Array
    (
        [country_code] => ID
        [latitude] => -6.16667
        [longitude] => 106.8
        [comments] => Java, Sumatra
    )
    Array
    (
        [country_code] => ID
        [latitude] => -6.16667
        [longitude] => 106.8
        [comments] => Java, Sumatra
    )

`country_code` 要素には、ISO 3166-1 alpha-2 で定められた国コードがそれぞれ入っています。 `latitude` と `longitude` 要素には、タイムゾーンの識別子に含まれる都市の座標が入ります。 `comments` 要素には (`false` でない場合)、 指定された国でこのタイムゾーンが適用される場所のヒントが入ります。 この情報はエンドユーザー向けの表現に適しています。

### 参考

- タイムゾーンの識別子を全て、または一部を取得する DateTimeZone::listIdentifiers() - すべてのタイムゾーン識別子を含む配列を返す

# DateTimeZone::getName

# timezone_name_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getName -- timezone_name_get — タイムゾーンの名前を返す

### 説明

オブジェクト指向型

public function DateTimeZone::getName(): string

手続き型

function timezone_name_get(DateTimeZone `$object`): string

タイムゾーンの名前を返します。

### パラメータ

`object`

  名前を取得したい DateTimeZone。

### 戻り値

タイムゾーンのタイプによって、異なる値を返します。 UTC オフセット(type 1 の場合)、 タイムゾーンの省略形(type 2 の場合)、 および IANA タイムゾーンデータベースに登録されているタイムゾーン識別子(type 3 の場合) です。これらは、同じオフセット かつ/または ルールで DateTimeZone オブジェクトを作るための文字列です。 たとえば `02:00`、 `CEST`、 タイムゾーン一覧 のタイムゾーン名のひとつを返します。

# DateTimeZone::getOffset

# timezone_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getOffset -- timezone_offset_get — GMT からのタイムゾーンのオフセットを返す

### 説明

オブジェクト指向型

public function DateTimeZone::getOffset(DateTimeInterface `$datetime`): int

手続き型

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

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

    int(32400)

# DateTimeZone::getTransitions

# timezone_transitions_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::getTransitions -- timezone_transitions_get — タイムゾーンの変遷を返す

### 説明

オブジェクト指向型

public function DateTimeZone::getTransitions(int `$timestampBegin` = `PHP_INT_MIN`, int `$timestampEnd` = 2147483647): array|false

手続き型

function timezone_transitions_get(DateTimeZone `$object`, int `$timestampBegin` = `PHP_INT_MIN`, int `$timestampEnd` = 2147483647): 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 | タイムゾーンの省略形

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | `timestampEnd` のデフォルト値が 2147483647 に変更されました。 以前は `PHP_INT_MAX` でした。

### 例

例1 timezone_transitions_get() の例

    <?php
    $timezone = new DateTimeZone("Europe/London");
    $transitions = $timezone->getTransitions();
    print_r(array_slice($transitions, 0, 3));
    ?>

上の例の出力は、 たとえば以下のようになります。

    Array
    (
        [0] => Array
            (
                [ts] => -2147483648
                [time] => 1901-12-13T20:45:52+00:00
                [offset] => -75
                [isdst] =>
                [abbr] => LMT
            )

        [1] => Array
            (
                [ts] => 442304971
                [time] => 1847-12-01T00:01:15+00:00
                [offset] => 0
                [isdst] =>
                [abbr] => GMT
            )

        [2] => Array
            (
                [ts] => -1691964000
                [time] => 1916-05-21T02:00:00+00:00
                [offset] => 3600
                [isdst] => 1
                [abbr] => BST
            )

    )

例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] => 1759058251
                [time] => 2025-09-28T11:17:31+00:00
                [offset] => 3600
                [isdst] => 1
                [abbr] => BST
            )

        [1] => Array
            (
                [ts] => 1761440400
                [time] => 2025-10-26T01:00:00+00:00
                [offset] => 0
                [isdst] =>
                [abbr] => GMT
            )

        [2] => Array
            (
                [ts] => 1774746000
                [time] => 2026-03-29T01:00:00+00:00
                [offset] => 3600
                [isdst] => 1
                [abbr] => BST
            )

    )

# DateTimeZone::listAbbreviations

# timezone_abbreviations_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::listAbbreviations -- timezone_abbreviations_list — 夏時間、オフセットおよびタイムゾーン名を含む連想配列を返す

### 説明

オブジェクト指向型

public static function DateTimeZone::listAbbreviations(): array

手続き型

function 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] =>
                [offset] => 34200
                [timezone_id] => Australia/Adelaide
            )

        [1] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/Broken_Hill
            )

        [2] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/Darwin
            )

        [3] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/North
            )

        [4] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/South
            )

        [5] => Array
            (
                [dst] =>
                [offset] => 34200
                [timezone_id] => Australia/Yancowinna
            )

    )

### 参考

- timezone_identifiers_list() - DateTimeZone::listIdentifiers のエイリアス

# DateTimeZone::listIdentifiers

# timezone_identifiers_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

DateTimeZone::listIdentifiers -- timezone_identifiers_list — すべてのタイムゾーン識別子を含む配列を返す

### 説明

オブジェクト指向型

public static function DateTimeZone::listIdentifiers(int `$timezoneGroup` = `DateTimeZone::ALL`, ?string `$countryCode` = `null`): array

手続き型

function timezone_identifiers_list(int `$timezoneGroup` = `DateTimeZone::ALL`, ?string `$countryCode` = `null`): array

» IANA Time Zone identifiers の一覧を返します。

> 注意: » Intl.DateTimeFormat や » Temporal.ZonedDateTime を使うと、 JavaScript でクライアント(ブラウザ) のタイムゾーンを検知することができます。

### パラメータ

`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 地域のコメントを付けて、識別子の一覧を取得する

    <?php
    $identifiers = DateTimeZone::listIdentifiers(DateTimeZone::ALL);

    foreach ($identifiers as $tzid) {
        $tz = new DateTimeZone($tzid);
        $comments = $tz->getLocation()['comments'];
        echo $tzid . " (" . ($comments ?: 'Whole region') . ")\n";
    }

上の例の出力は、 たとえば以下のようになります。

    America/Antigua (Whole region)
    America/Araguaina (Tocantins)
    America/Argentina/Buenos_Aires (Buenos Aires (BA, CF))
    America/Argentina/Catamarca (Catamarca (CT), Chubut (CH))
    America/Argentina/Cordoba (Argentina (most areas: CB, CC, CN, ER, FM, MN, SE, SF))
    // (Output trimmed due to length)

例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 のエイリアス

## 目次

- DateTimeZone::__construct — 新しい DateTimeZone オブジェクトを作成する
- DateTimeZone::getLocation — タイムゾーンの位置情報を返す
- DateTimeZone::getName — タイムゾーンの名前を返す
- DateTimeZone::getOffset — GMT からのタイムゾーンのオフセットを返す
- DateTimeZone::getTransitions — タイムゾーンの変遷を返す
- DateTimeZone::listAbbreviations — 夏時間、オフセットおよびタイムゾーン名を含む連想配列を返す
- DateTimeZone::listIdentifiers — すべてのタイムゾーン識別子を含む配列を返す

# 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 function __construct(string `$duration`)
public static function createFromDateString(string `$datetime`): DateInterval
public function 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

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::__construct — 新しい DateInterval オブジェクトを作成する

### 説明

public function 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::createFromDateString

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::createFromDateString — 文字列の相対部分から DateInterval を作成する

### 説明

オブジェクト指向型

public static function DateInterval::createFromDateString(string `$datetime`): DateInterval

手続き型

function date_interval_create_from_date_string(string `$datetime`): DateInterval|false

DateTimeImmutable のコンストラクタで使われている日付/時刻パーサーを用いて、パースされた文字列の相対部分から DateInterval を作成します。

### パラメータ

`datetime`

  相対部分を含む日付。 特に、strtotime() や DateTimeImmutable、 DateTime が使うパーサーがサポートする 相対書式 を使って DateInterval を作ることができます。

  `P7D` のような ISO-8601 フォーマットの文字列を使うには、 DateInterval::__construct() を使わなければいけません。

### 戻り値

成功した場合に DateInterval を返します。 手続き型 の場合は、失敗したときに `false` を返します。

### エラー / 例外

オブジェクト指向のAPIのみ、 無効な日付/時刻の文字列が渡された場合に DateMalformedIntervalStringException がスローされます。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 仮の戻り値の型が、DateInterval になりました。 これより前のバージョンでは、DateInterval|false でした。
8.3.0 | 無効な文字列が渡された場合、 DateInterval::createFromDateString() は DateMalformedIntervalStringException をスローするようになりました。 これより前のバージョンでは、 警告が発生して `false` を返していました。 date_interval_create_from_date_string() は変更されていません。
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::format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DateInterval::format — 間隔をフォーマットする

### 説明

public function 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 オブジェクトの差を返す

## 目次

- DateInterval::__construct — 新しい DateInterval オブジェクトを作成する
- DateInterval::createFromDateString — 文字列の相対部分から DateInterval を作成する
- DateInterval::format — 間隔をフォーマットする

# 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 function __construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
int `$recurrences`,
int `$options` = 0
)
public function __construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
DateTimeInterface `$end`,
int `$options` = 0
)
public function __construct(string `$isostr`, int `$options` = 0)
public static function createFromISO8601String(string `$specification`, int `$options` = 0): static
public function getDateInterval(): DateInterval
public function getEndDate(): ?DateTimeInterface
public function getRecurrences(): ?int
public function getStartDate(): DateTimeInterface
}

## 定義済み定数

`DatePeriod::EXCLUDE_START_DATE` int

  開始日を含まない。DatePeriod::__construct() で使用します。

`DatePeriod::INCLUDE_END_DATE` int

  終了日を含む。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.4.0 | クラス定数が型付けされました。
8.2.0 | 定数 `DatePeriod::INCLUDE_END_DATE` と プロパティ include_end_date が追加されました。
8.0.0 | DatePeriod は、 IteratorAggregate を実装するようになりました。 これより前のバージョンでは、 Traversable を実装していました。

# DatePeriod::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

DatePeriod::__construct — 新しい DatePeriod オブジェクトを作成する

### 説明

public function DatePeriod::__construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
int `$recurrences`,
int `$options` = 0
)
public function DatePeriod::__construct(
DateTimeInterface `$start`,
DateInterval `$interval`,
DateTimeInterface `$end`,
int `$options` = 0
)
警告

以下のコンストラクタのバリエーションは、推奨されなくなりました。

public function DatePeriod::__construct(string `$isostr`, int `$options` = 0)

このコンストラクタのバリエーションは、PHP 8.4.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 をスローします。 PHP 8.3 より前のバージョンでは、Exception がスローされていました。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `isostr` を使うシグネチャは非推奨となりました。 代わりに DatePeriod::createFromISO8601String() を使ってください。
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";
    }

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

    Deprecated: Calling DatePeriod::__construct(string $isostr, int $options = 0) is deprecated, use DatePeriod::createFromISO8601String() instead in script on line 11
    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` を渡したりしても動作しません。

# DatePeriod::createFromISO8601String

(PHP 8 >= 8.3.0)

DatePeriod::createFromISO8601String — ISO8601 形式の文字列から、新しい DatePeriod オブジェクトを作成する

### 説明

public static function 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::getDateInterval

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getDateInterval — 間隔を取得する

### 説明

オブジェクト指向型

public function DatePeriod::getDateInterval(): DateInterval

期間に適用される間隔を表す DateInterval object を取得する。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

DateInterval object を返す。

### 例

例1 DatePeriod::getDateInterval() の例

    <?php
    $period = DatePeriod::createFromIso8601String('R7/2016-05-16T00:00:00Z/P1D');
    $interval = $period->getDateInterval();
    echo $interval->format('%d day');

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

    1 day

### 参考

- DatePeriod::getStartDate() - 開始日を取得する
- DatePeriod::getEndDate() - 終了日を取得する

# DatePeriod::getEndDate

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getEndDate — 終了日を取得する

### 説明

オブジェクト指向型

public function 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::getRecurrences

(PHP 7 >= 7.2.17/7.3.4, PHP 8)

DatePeriod::getRecurrences — 繰り返しの数を取得する

### 説明

オブジェクト指向型

public function 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::getStartDate

(PHP 5 >= 5.6.5, PHP 7, PHP 8)

DatePeriod::getStartDate — 開始日を取得する

### 説明

オブジェクト指向型

public function DatePeriod::getStartDate(): DateTimeInterface

期間の開始日を取得する。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

DatePeriod が DateTimeImmutable object を `start` パラメータに用いて初期化されている場合は DateTimeImmutable object を返す。

それ例外の場合は DateTime object を返す。

### 例

例1 DatePeriod::getStartDate() の例

    <?php
    $period = DatePeriod::createFromIso8601String('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() - 間隔を取得する

## 目次

- DatePeriod::__construct — 新しい DatePeriod オブジェクトを作成する
- DatePeriod::createFromISO8601String — ISO8601 形式の文字列から、新しい DatePeriod オブジェクトを作成する
- DatePeriod::getDateInterval — 間隔を取得する
- DatePeriod::getEndDate — 終了日を取得する
- DatePeriod::getRecurrences — 繰り返しの数を取得する
- DatePeriod::getStartDate — 開始日を取得する

# 日付・時刻 関数

# checkdate

(PHP 4, PHP 5, PHP 7, PHP 8)

checkdate — グレゴリオ暦の日付/時刻の妥当性を確認します

### 説明

function 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 タイムスタンプに変換する

# date

(PHP 4, PHP 5, PHP 7, PHP 8)

date — Unixタイムスタンプを書式化する

### 説明

function date(string `$format`, ?int `$timestamp` = `null`): string

指定された引数 `timestamp` (Unixタイムスタンプ) を、与えられた フォーマット文字列によりフォーマットし、日付文字列を返します。 タイムスタンプが与えられない場合は、現在の時刻が使われます。 つまり `timestamp` はオプションであり そのデフォルト値は time() の値です。

警告

Unixタイムスタンプはタイムゾーンを処理しません。 タイムゾーン情報が付加された日付/時刻の情報を書式化するには、 DateTimeImmutable クラスや、 DateTimeInterface::format() を使って下さい。

### パラメータ

`format`

  DateTimeInterface::format() が受け入れるフォーマット。

  > 注意: date() 関数は、マイクロ秒については常に `000000` を生成します。 というのも、この関数が受け取るパラメータは int 型だからです。 一方 DateTimeInterface 型のオブジェクトをマイクロ秒つきで作成した場合は、 DateTimeInterface::format() はマイクロ秒にも対応しています。

`timestamp`
  オプションのパラメータ `timestamp` は、 int 型の Unix タイムスタンプです。 `timestamp` が指定されなかったり、`null` だった場合のデフォルト値は、 現在の時刻です。言い換えると、デフォルトは time() の返り値となります。

### 戻り値

フォーマットされた日付を表す文字列を返します。

### エラー / 例外

すべての日付/時刻関数は、 有効なタイムゾーンが設定されていない場合に `E_WARNING` を発生させます。 date_default_timezone_set() も参照ください。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `timestamp` は、nullable になりました。

### 例

例1 date() の例

    <?php
    // set the default timezone to use.
    date_default_timezone_set('UTC');

    // Prints something like: Monday
    echo date("l") . "\n";

    // Prints something like: Monday 8th of August 2005 03:12:46 PM
    echo date('l jS \of F Y h:i:s A') . "\n";

    // Prints: July 1, 2000 is on a Saturday
    echo "July 1, 2000 is on a " . date("l", mktime(0, 0, 0, 7, 1, 2000)) . "\n";

    /* use the constants in the format parameter */
    // prints something like: Wed, 25 Sep 2013 15:28:57 -0700
    echo date(DATE_RFC2822) . "\n";

    // prints something like: 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() フォーマットのいくつかの例を示します。 現在の実装で特別な意味がある文字や今後の PHP のバージョンで意味が 割り付けられるであろう文字については、望ましくない結果を避けるために エスケープする必要があることに注意してください。エスケープを する際には、改行文字 \n のような文字を回避するために シングルクォートを使用してください。

例3 date() のフォーマット指定

    <?php
    // Assuming today is March 10th, 2001, 5:16:18 pm, and that we are in the
    // Mountain Standard Time (MST) Time Zone
    date_default_timezone_set("America/Phoenix");

    echo date("F j, Y, g:i a") . "\n";                 // March 10, 2001, 5:16 pm
    echo date("m.d.y") . "\n";                         // 03.10.01
    echo date("j, n, Y") . "\n";                       // 10, 3, 2001
    echo date("Ymd") . "\n";                           // 20010310
    echo date('h-i-s, j-m-y, it is w Day') . "\n";     // 05-16-18, 10-03-01, 1631 1618 6 Satpm01
    echo date('\i\t \i\s \t\h\e jS \d\a\y.') . "\n";   // it is the 10th day.
    echo date("D M j G:i:s T Y") . "\n";               // Sat Mar 10 17:16:18 MST 2001
    echo date('H:m:s \m \i\s\ \m\o\n\t\h') . "\n";     // 17:03:18 m is month
    echo date("H:i:s") . "\n";                         // 17:16:18
    echo date("Y-m-d H:i:s") . "\n";                   // 2001-03-10 17:16:18 (the MySQL DATETIME format)

他の言語で日付をフォーマットする用途には、 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 タイムスタンプを返す
- 定義済みの定数

# date_add

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_add — DateTime::add() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 DateTime::add()

# date_create

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_create — 新しい DateTime オブジェクトを作成する

### 説明

function 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 オブジェクトを返す

# date_create_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_create_from_format — DateTime::createFromFormat() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 DateTime::createFromFormat()

# date_create_immutable

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

date_create_immutable — 新しい DateTimeImmutable オブジェクトを作成する

### 説明

function date_create_immutable(string `$datetime` = "now", ?DateTimeZone `$timezone` = `null`): DateTimeImmutable|false

これは DateTimeImmutable::__construct() の手続き型バージョンです。

DateTimeImmutable のコンストラクタと異なり、 `datetime` が不正な文字列だった場合には 例外をスローする代わりに `false` を返します。

### パラメータ

DateTimeImmutable::__construct を参照ください。

### 戻り値

新しい DateTimeImmutable のインスタンスを返します。失敗した場合に `false` を返します

### 参考

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

# date_date_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_date_set — DateTime::setDate() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 DateTime::setDate()

# date_default_timezone_get

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

date_default_timezone_get — スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを取得する

### 説明

function 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() . "\n";
    }

    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_set

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

date_default_timezone_set — スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを設定する

### 説明

function 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();
    $ini_tz = ini_get('date.timezone');

    if (strcmp($script_tz, $ini_tz)){
        echo 'Script timezone differs from ini-set timezone.';
    } else {
        echo 'Script timezone and ini-set timezone match.';
    }

### 参考

- date_default_timezone_get() - スクリプト中の日付/時刻関数で使用されるデフォルトタイムゾーンを取得する
- サポートされるタイムゾーンのリスト

# date_diff

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_diff — DateTime::diff() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 DateTime::diff()

# date_format

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_format — DateTime::format() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 DateTime::format()

# date_get_last_errors

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_get_last_errors — DateTimeImmutable::getLastErrors() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 DateTimeImmutable::getLastErrors()

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

# date_interval_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_interval_format — DateInterval::format() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 DateInterval::format()

# date_isodate_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_isodate_set — DateTime::setISODate() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 DateTime::setISODate()

# date_modify

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_modify — DateTime::modify() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 DateTime::modify()

# date_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_offset_get — DateTime::getOffset() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 DateTime::getOffset()

# date_parse

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_parse — 指定した日付/時刻の詳細な情報を連想配列で返す

### 説明

function 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_from_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_parse_from_format — 指定した書式でフォーマットされた日付についての情報を取得する

### 説明

function 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] => 0
        [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: Not enough data available to satisfy format

### 参考

- DateTimeImmutable::createFromFormat() - 時刻の文字列を指定されたフォーマットに従ってパースする
- checkdate() - グレゴリオ暦の日付/時刻の妥当性を確認します

# date_sub

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_sub — DateTime::sub() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 DateTime::sub()

### 参考

- DateTimeImmutable::sub() - 年月日時分秒の値を引く
- DateTime::sub() - 年月日時分秒の値を DateTime オブジェクトから引く

# date_sun_info

(PHP 5 >= 5.1.2, PHP 7, PHP 8)

date_sun_info — 日の出/日の入り時刻と薄明 (twilight) の開始/終了時刻の情報を含む配列を返す

### 説明

function 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 白夜の例(Tromsø, 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_sunrise

(PHP 5, PHP 7, PHP 8)

date_sunrise — 指定した日付と場所についての日の出時刻を返す

警告

この関数は PHP 8.1.0 で 非推奨 になります。 この機能に頼らないことを強く推奨します。 代わりに date_sun_info() を使ってください。

### 説明

#[\Deprecated]
function 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);

上の例の出力は、 たとえば以下のようになります。

    Deprecated: Constant SUNFUNCS_RET_STRING is deprecated in script on line 10
    Deprecated: Function date_sunrise() is deprecated since 8.1, use date_sun_info() instead in script on line 10
    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));

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

    Deprecated: Constant SUNFUNCS_RET_STRING is deprecated in script on line 3
    Deprecated: Function date_sunrise() is deprecated since 8.1, use date_sun_info() instead in script on line 3
    bool(false)

### 参考

- date_sun_info() - 日の出/日の入り時刻と薄明 (twilight) の開始/終了時刻の情報を含む配列を返す

# date_sunset

(PHP 5, PHP 7, PHP 8)

date_sunset — 指定した日付と場所についての日の入り時刻を返す

警告

この関数は PHP 8.1.0 で 非推奨 になります。 この機能に頼らないことを強く推奨します。 代わりに date_sun_info() を使ってください。

### 説明

#[\Deprecated]
function 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);

上の例の出力は、 たとえば以下のようになります。

    Deprecated: Constant SUNFUNCS_RET_STRING is deprecated in script on line 10
    Deprecated: Function date_sunset() is deprecated since 8.1, use date_sun_info() instead in script on line 10
    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));

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

    Deprecated: Constant SUNFUNCS_RET_STRING is deprecated in script on line 3
    Deprecated: Function date_sunset() is deprecated since 8.1, use date_sun_info() instead in script on line 3
    bool(false)

### 参考

- date_sun_info() - 日の出/日の入り時刻と薄明 (twilight) の開始/終了時刻の情報を含む配列を返す

# date_time_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_time_set — DateTime::setTime() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 DateTime::setTime()

# date_timestamp_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_timestamp_get — DateTime::getTimestamp() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 DateTime::getTimestamp()

# date_timestamp_set

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

date_timestamp_set — DateTime::setTimestamp() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 DateTime::setTimestamp()

# date_timezone_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_timezone_get — DateTime::getTimezone() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 DateTime::getTimezone()

# date_timezone_set

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

date_timezone_set — DateTime::setTimezone() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 DateTime::setTimezone()

# getdate

(PHP 4, PHP 5, PHP 7, PHP 8)

getdate — 日付/時刻情報を取得する

### 説明

function 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() - ロケール情報を設定する

# gettimeofday

(PHP 4, PHP 5, PHP 7, PHP 8)

gettimeofday — 現在の時間を得る

### 説明

function 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

# gmdate

(PHP 4, PHP 5, PHP 7, PHP 8)

gmdate — GMT/UTC の日付/時刻を書式化する

### 説明

function 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() の例

    <?php
    date_default_timezone_set("Europe/Helsinki");

    echo date("M d Y H:i:s e", mktime(0, 0, 0, 1, 1, 1998)) . "\n";
    echo gmdate("M d Y H:i:s e", mktime(0, 0, 0, 1, 1, 1998));

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

    Jan 01 1998 00:00:00 Europe/Helsinki
    Dec 31 1997 22:00:00 UTC

### 参考

- DateTimeImmutable::__construct() - 新しい DateTimeImmutable オブジェクトを返す
- DateTimeInterface::format() - 指定した書式でフォーマットした日付を返す
- date() - Unixタイムスタンプを書式化する
- mktime() - 日付を Unix のタイムスタンプとして取得する
- gmmktime() - GMT 日付から Unix タイムスタンプを取得する
- IntlDateFormatter::format() - 日付/時刻 の値を文字列としてフォーマットする

# gmmktime

(PHP 4, PHP 5, PHP 7, PHP 8)

gmmktime — GMT 日付から Unix タイムスタンプを取得する

### 説明

function 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
    date_default_timezone_set("Indian/Maldives");

    echo "July 1, 2000 is on a " . date("l", gmmktime(0, 0, 0, 7, 1, 2000));

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

    July 1, 2000 is on a Saturday

### 参考

- DateTimeImmutable
- mktime() - 日付を Unix のタイムスタンプとして取得する
- date() - Unixタイムスタンプを書式化する
- time() - 現在の Unix タイムスタンプを返す

# gmstrftime

(PHP 4, PHP 5, PHP 7, PHP 8)

gmstrftime — ロケールの設定に基づいて GMT/UTC 時刻/日付をフォーマットする

警告

この関数は PHP 8.1.0 で 非推奨 になります。この関数に頼らないことを強く推奨します。

この関数の代替として、これらが使えます:

- gmdate()
- IntlDateFormatter::format()

### 説明

#[\Deprecated]
function 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, 'es_ES.UTF-8');
    date_default_timezone_set('EST');

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

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

    Deprecated: Function strftime() is deprecated since 8.1, use IntlDateFormatter::format() instead in script on line 6
    diciembre 31 1998 20:00:00

    Deprecated: Function gmstrftime() is deprecated since 8.1, use IntlDateFormatter::format() instead in script on line 7
    enero 01 1999 01:00:00

### 参考

- IntlDateFormatter::format() - 日付/時刻 の値を文字列としてフォーマットする
- DateTimeInterface::format() - 指定した書式でフォーマットした日付を返す
- strftime() - ロケールの設定に基づいてローカルな日付・時間をフォーマットする

# idate

(PHP 5, PHP 7, PHP 8)

idate — ローカルな時刻/日付の一部を整数として整形する

### 説明

function 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) . "\n";

    $timestamp = strtotime('1st January 2024'); // 1704067200
    echo idate('y', $timestamp);

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

    4
    24

### 参考

- DateTimeInterface::format() - 指定した書式でフォーマットした日付を返す
- date() - Unixタイムスタンプを書式化する
- getdate() - 日付/時刻情報を取得する
- time() - 現在の Unix タイムスタンプを返す

# localtime

(PHP 4, PHP 5, PHP 7, PHP 8)

localtime — ローカルタイムを得る

### 説明

function 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() - 日付/時刻情報を取得する

# microtime

(PHP 4, PHP 5, PHP 7, PHP 8)

microtime — 現在の Unix タイムスタンプをマイクロ秒まで返す

### 説明

function 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(10_000);

    $time_end = microtime(true);
    $time = $time_end - $time_start;

    print "Did nothing in $time seconds\n";

例2 microtime() と `REQUEST_TIME_FLOAT` の例

    <?php
    // ランダムな時間のスリープ
    usleep(random_int(10_000, 1_000_000));

    // REQUEST_TIME_FLOAT をスーパーグローバル $_SERVER から取得できます。
    // ここにはリクエスト開始時のタイムスタンプがマイクロ秒の精度で記録されています。
    $time = microtime(true) - $_SERVER["REQUEST_TIME_FLOAT"];

    echo "Did nothing in $time seconds\n";

### 参考

- time() - 現在の Unix タイムスタンプを返す
- hrtime() - システムの高精度な時刻を取得する

# mktime

(PHP 4, PHP 5, PHP 7, PHP 8)

mktime — 日付を Unix のタイムスタンプとして取得する

### 説明

function 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)) . "\n";

    // 出力例: 2006-04-05T01:02:03+00:00
    echo date('c', mktime(1, 2, 3, 4, 5, 2006)) . "\n";

上の例の出力は、 たとえば以下のようになります。

    July 1, 2000 is on a Saturday
    2006-04-05T01:02:03+00:00

例2 mktime() の例

mktime() は入力日付の有効性を確認しており、 範囲外の入力を自動的に修正して計算してくれるので便利です。 例えば、以下の各行はいずれも文字列 "Jan-01-1998"を出力します。

    <?php
    date_default_timezone_set('America/New_York');

    echo date("c", mktime(0, 0, 0, 12, 32, 1997)) . "\n";
    echo date("c", mktime(0, 0, 0, 13, 1, 1997)) . "\n";
    echo date("c", mktime(0, 0, 0, 1, 1, 1998)) . "\n";
    echo date("c", mktime(0, 0, 0, 1, 1, 98)) . "\n";

上の例の出力は、 たとえば以下のようになります。

    1998-01-01T00:00:00-05:00
    1998-01-01T00:00:00-05:00
    1998-01-01T00:00:00-05:00
    1998-01-01T00:00:00-05:00

例3 mktime 関数を、相対日付を検出するために使う

    <?php
    date_default_timezone_set('Asia/Tokyo');

    $tomorrow  = mktime(0, 0, 0, date("m")  , date("d")+1, date("Y"));
    print date('c', $tomorrow) . "\n";

    $lastmonth = mktime(0, 0, 0, date("m")-1, date("d"),   date("Y"));
    print date('c', $lastmonth) . "\n";

    $nextyear  = mktime(0, 0, 0, date("m"),   date("d"),   date("Y")+1) . "\n";
    print date('c', $nextyear) . "\n";

上の例の出力は、 たとえば以下のようになります。

    2025-09-30T00:00:00+09:00
    2025-08-29T00:00:00+09:00
    2026-09-29T00:00:00+09:00

> 注意:

> 夏時間の影響により、 1日または1か月の秒数を加減算するより、 このサンプルの方が信頼性が高い場合があります。

例4 月の末日

指定した月の最後の日は次の月の -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) . "\n";

    $lastday = mktime(0, 0, 0, 4, -31, 2000);
    echo 'Last day in Feb 2000 is: ', date('d', $lastday) . "\n";

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

    Last day in Feb 2000 is: 29
    Last day in Feb 2000 is: 29

### 参考

- DateTimeImmutable
- checkdate() - グレゴリオ暦の日付/時刻の妥当性を確認します
- gmmktime() - GMT 日付から Unix タイムスタンプを取得する
- date() - Unixタイムスタンプを書式化する
- time() - 現在の Unix タイムスタンプを返す

# strftime

(PHP 4, PHP 5, PHP 7, PHP 8)

strftime — ロケールの設定に基づいてローカルな日付・時間をフォーマットする

警告

この関数は PHP 8.1.0 で 非推奨 になります。この関数に頼らないことを強く推奨します。

この関数の代替として、これらが使えます:

- date()
- IntlDateFormatter::format()

### 説明

#[\Deprecated]
function 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() の定義

# strptime

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

strptime — strftime() が生成した日付/時刻をパースする

警告

この関数は PHP 8.1.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function 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 の記事 を参照ください。

### 参考

- IntlDateFormatter::parse() - 文字列をパースしてタイムスタンプにする
- DateTime::createFromFormat() - 指定した書式で時刻文字列をパースする
- checkdate() - グレゴリオ暦の日付/時刻の妥当性を確認します
- strftime() - ロケールの設定に基づいてローカルな日付・時間をフォーマットする
- date_parse_from_format() - 指定した書式でフォーマットされた日付についての情報を取得する

# strtotime

(PHP 4, PHP 5, PHP 7, PHP 8)

strtotime — 英文形式の日付を Unix タイムスタンプに変換する

### 説明

function 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 が生成した日付/時刻をパースする

# time

(PHP 4, PHP 5, PHP 7, PHP 8)

time — 現在の Unix タイムスタンプを返す

### 説明

function 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 タイムスタンプをマイクロ秒まで返す

# timezone_abbreviations_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_abbreviations_list — DateTimeZone::listAbbreviations() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 DateTimeZone::listAbbreviations()

# timezone_identifiers_list

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_identifiers_list — DateTimeZone::listIdentifiers() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 DateTimeZone::listIdentifiers()

# timezone_location_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

timezone_location_get — DateTimeZone::getLocation() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 DateTimeZone::getLocation()

# timezone_name_from_abbr

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

timezone_name_from_abbr — 略称とUTCオフセットから、タイムゾーン名を推測して返す

### 説明

function 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 のエイリアス

# timezone_name_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_name_get — DateTimeZone::getName() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 DateTimeZone::getName()

# timezone_offset_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_offset_get — DateTimeZone::getOffset() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 DateTimeZone::getOffset()

# timezone_open

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_open — DateTimeZone::__construct() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 DateTimeZone::__construct()

# timezone_transitions_get

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

timezone_transitions_get — DateTimeZone::getTransitions() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 DateTimeZone::getTransitions()

# timezone_version_get

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

timezone_version_get — timezonedb のバージョンを取得する

### 説明

function 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

### 参考

- サポートするタイムゾーンの一覧

## 目次

- 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 (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` にマッチした場合にこれらふたつの日付要素が代わりに設定されます。

> 年だけの指定を一貫してパースしたい場合は、 `Y` を指定して DateTimeImmutable::createFromFormat() を使ってください。

警告

シンボル `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.4.0 | `number` シンボルは、 再びプラス符号の後に、マイナス符号を受け入れるようになりました。 たとえば、`+-2` のようなフォーマットや、 他の複数の符号の組み合わせです。
8.2.0 | `number` シンボルは、 プラス符号の後に、マイナス符号を受け入れなくなりました。 たとえば、`+-2` のようなフォーマットです。
7.0.8 | 週の始まりが常に月曜日となりました。 これより前のバージョンでは、日曜日も週の始まりとみなされていました。

# サポートされるタイムゾーンのリスト

## 目次

- アフリカ
- アメリカ
- 南極
- 北極
- アジア
- 大西洋
- オーストラリア
- ヨーロッパ
- インド
- 太平洋
- その他

これは、PHP がサポートしているタイムゾーンの完全なリストです。例えば date_default_timezone_set() などで使用します。

警告

ここに挙げられていないタイムゾーンの挙動は未定義です。

> 注意: 最新バージョンのタイムゾーンデータベースは、PECL の » timezonedb からインストールできます。

> 注意: このリストの元になっているのは、タイムゾーンデータベース バージョン 2026.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/Coyhaique
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 |

## 北極

北極
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/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/Choibalsan | 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 function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function 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 function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function 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 function Error::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Error::getMessage(): string
final public function Error::getPrevious(): ?Throwable
final public function Error::getCode(): int
final public function Error::getFile(): string
final public function Error::getLine(): int
final public function Error::getTrace(): array
final public function Error::getTraceAsString(): string
public function Error::__toString(): string
private function 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 function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function 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 function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function 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 function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function 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 function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function 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 function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function 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 function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

- インストール/設定
  - インストール手順
  - 実行時設定
- 定義済み定数
- 例
  - 日付/時刻 の算術
- DateTime — DateTime クラス
  - DateTime::add — 年月日時分秒の値を加えることで、DateTime オブジェクトを変更する
  - DateTime::__construct — 新しい DateTime オブジェクトを返す
  - DateTime::createFromFormat — 指定した書式で時刻文字列をパースする
  - DateTime::createFromImmutable — 与えられた DateTimeImmutable オブジェクトをカプセル化した、新しい DateTime のインスタンスを返す
  - DateTime::createFromInterface — 指定された DateTimeInterface オブジェクトをカプセル化した、新しい DateTime オブジェクトを返す
  - DateTime::createFromTimestamp — Unix タイムスタンプからインスタンスを生成する
  - DateTime::getLastErrors — DateTimeImmutable::getLastErrors のエイリアス
  - DateTime::modify — タイムスタンプを変更する
  - DateTime::__set_state — __set_state ハンドラ
  - DateTime::setDate — 日付を設定する
  - DateTime::setISODate — ISO 形式の日付を設定する
  - DateTime::setMicrosecond — 時刻のマイクロ秒部分を設定する
  - 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::createFromTimestamp — Unix タイムスタンプからインスタンスを生成する
  - DateTimeImmutable::getLastErrors — 警告およびエラーを返す
  - DateTimeImmutable::modify — タイムスタンプを変更した新しいオブジェクトを作る
  - DateTimeImmutable::__set_state — __set_state ハンドラ
  - DateTimeImmutable::setDate — 日付を設定する
  - DateTimeImmutable::setISODate — ISO 日付を設定する
  - DateTimeImmutable::setMicrosecond — 時刻のマイクロ秒部分を設定する
  - DateTimeImmutable::setTime — 時刻を設定する
  - DateTimeImmutable::setTimestamp — Unix タイムスタンプを用いて日付と時刻を設定する
  - DateTimeImmutable::setTimezone — タイムゾーンを設定する
  - DateTimeImmutable::sub — 年月日時分秒の値を引く
- DateTimeInterface — DateTimeInterface インターフェイス
  - DateTimeInterface::diff — ふたつの DateTime オブジェクトの差を返す
  - DateTimeInterface::format — 指定した書式でフォーマットした日付を返す
  - DateTimeInterface::getMicrosecond — Unix タイムスタンプのマイクロ秒部分を取得する
  - DateTimeInterface::getOffset — タイムゾーンのオフセットを返す
  - DateTimeInterface::getTimestamp — Unix タイムスタンプを取得する
  - DateTimeInterface::getTimezone — 指定した DateTime に関連するタイムゾーンを返す
  - DateTime::__serialize — DateTime をシリアライズする
  - DateTime::__unserialize — 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 クラス

# High resolution timing

# はじめに

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.

# インストール/設定

## 目次

- インストール手順

## インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/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 function getFrequency(): int
public static function getTicks(): int
public static function getTicksSince(int `$start`): int
}

# HRTime\PerformanceCounter::getFrequency

(PECL hrtime >= 0.4.3)

HRTime\PerformanceCounter::getFrequency — Timer frequency in ticks per second

### 説明

public static function 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.

# HRTime\PerformanceCounter::getTicks

(PECL hrtime >= 0.6.0)

HRTime\PerformanceCounter::getTicks — Current ticks from the system

### 説明

public static function HRTime\PerformanceCounter::getTicks(): int

Returns the ticks count.

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns int indicating the ticks count.

# HRTime\PerformanceCounter::getTicksSince

(PECL hrtime >= 0.6.0)

HRTime\PerformanceCounter::getTicksSince — Ticks elapsed since the given value

### 説明

public static function 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.

## 目次

- 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

# The HRTime\StopWatch class

(PECL hrtime >= 0.4.3)

## はじめに

## クラス概要

class HRTime\StopWatch extends HRTime\PerformanceCounter {
/* メソッド */
public function getElapsedTicks(): int
public function getElapsedTime(int `$unit` = ?): float
public function getLastElapsedTicks(): int
public function getLastElapsedTime(int `$unit` = ?): float
public function isRunning(): bool
public function start(): void
public function stop(): void
/* 継承したメソッド */
public static function HRTime\PerformanceCounter::getFrequency(): int
public static function HRTime\PerformanceCounter::getTicks(): int
public static function HRTime\PerformanceCounter::getTicksSince(int `$start`): int
}

# HRTime\StopWatch::getElapsedTicks

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getElapsedTicks — すべてのインターバルの経過ティック数を取得する

### 説明

public function HRTime\StopWatch::getElapsedTicks(): int

以前に閉じたすべてのインターバルの経過ティック数を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

経過ティック数を示す int を返します。

# HRTime\StopWatch::getElapsedTime

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getElapsedTime — すべてのインターバルの経過時間を取得する

### 説明

public function HRTime\StopWatch::getElapsedTime(int `$unit` = ?): float

以前に閉じたすべてのインターバルの経過時間を取得します。

### パラメータ

`unit`
  HRTime\Unit 定数で表される時間単位。デフォルトは HRTime\Unit::SECOND です。

### 戻り値

経過時間を示す float を返します。

# HRTime\StopWatch::getLastElapsedTicks

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getLastElapsedTicks — 最後のインターバルの経過ティック数を取得する

### 説明

public function HRTime\StopWatch::getLastElapsedTicks(): int

直前に閉じたインターバルの経過ティック数を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

経過ティック数を示す int を返します。

# HRTime\StopWatch::getLastElapsedTime

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::getLastElapsedTime — 最後のインターバルの経過時間を取得する

### 説明

public function HRTime\StopWatch::getLastElapsedTime(int `$unit` = ?): float

直前に閉じたインターバルの経過時間を取得します。

### パラメータ

`unit`
  HRTime\Unit 定数で表される時間単位。デフォルトは HRTime\Unit::SECOND です。

### 戻り値

経過時間を示す float を返します。

# HRTime\StopWatch::isRunning

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::isRunning — 計測が実行中かどうか

### 説明

public function HRTime\StopWatch::isRunning(): bool

計測が開始されたかどうかを示します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

計測が実行中かどうかを示す bool を返します。

# HRTime\StopWatch::start

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::start — Start time measurement

### 説明

public function 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.

# HRTime\StopWatch::stop

(PECL hrtime >= 0.4.3)

HRTime\StopWatch::stop — Stop time measurement

### 説明

public function HRTime\StopWatch::stop(): void

Stop the time measurement for the previously started interval.

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns void.

## 目次

- HRTime\StopWatch::getElapsedTicks — すべてのインターバルの経過ティック数を取得する
- HRTime\StopWatch::getElapsedTime — すべてのインターバルの経過時間を取得する
- HRTime\StopWatch::getLastElapsedTicks — 最後のインターバルの経過ティック数を取得する
- HRTime\StopWatch::getLastElapsedTime — 最後のインターバルの経過時間を取得する
- HRTime\StopWatch::isRunning — 計測が実行中かどうか
- HRTime\StopWatch::start — Start time measurement
- HRTime\StopWatch::stop — Stop time measurement

# 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`

- インストール/設定
  - インストール手順
- 例
  - 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 — すべてのインターバルの経過ティック数を取得する
  - HRTime\StopWatch::getElapsedTime — すべてのインターバルの経過時間を取得する
  - HRTime\StopWatch::getLastElapsedTicks — 最後のインターバルの経過ティック数を取得する
  - HRTime\StopWatch::getLastElapsedTime — 最後のインターバルの経過時間を取得する
  - HRTime\StopWatch::isRunning — 計測が実行中かどうか
  - HRTime\StopWatch::start — Start time measurement
  - HRTime\StopWatch::stop — Stop time measurement
- HRTime\Unit — The HRTime\Unit class

- カレンダー
  - インストール/設定
  - 定義済み定数
  - カレンダー 関数
- 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

# ファイルシステム

# ダイレクト IO

# はじめに

PHP は、POSIX 標準(第 6 章)に記述されたダイレクト IO 関数をサポートします。 これらは、C 言語のストリーム I/O 関数 (fopen(), fread(),..) よりも低レベルの I/O 関数の実装です。 DIO 関数の使用は、あるデバイスを直接制御することが必要な場合のみ考えるべきです。 その他の場合は、標準の ファイルシステム関数の方が適切です。

# インストール/設定

## 目次

- インストール手順
- リソース型

## インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/dio.

## リソース型

この拡張モジュールでは、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

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_close — fd で指定したファイル記述子を閉じる

### 説明

function 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 ライブラリの入出力ストリーム関数が許すよりも低レベルでファイルをオープンする (必要ならファイルを作成する)

# dio_fcntl

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_fcntl — fd について C ライブラリの fcntl を実行する

### 説明

function 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_SETLKW` の際に以下のキーを保持します。

  - `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 環境にはまだ実装されていません。

# dio_open

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_open — C ライブラリの入出力ストリーム関数が許すよりも低レベルでファイルをオープンする (必要ならファイルを作成する)

### 説明

function 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_read

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_read — ファイル記述子からバイトデータを読み込む

### 説明

function dio_read(resource `$fd`, int `$len` = 1024): string

関数 dio_read() は 記述子 `fd` で示されるファイルから `len` バイトを読み込み、それを返します。

### パラメータ

`fd`

  dio_open() が返すファイル記述子。

`len`

  読み込むバイト数。指定されなかった場合は dio_read() は 1K サイズのブロックを読み込みます。

### 戻り値

`fd` から読み込んだバイトデータを返します。

### 参考

- dio_write() - オプションで丸め長さを指定してデータを書き込む

# dio_seek

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_seek — fd 上で whence から pos に移動する

### 説明

function 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);
    ?>

# dio_stat

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_stat — ファイル記述子 fd に関する stat 情報を取得する

### 説明

function 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_tcsetattr

(PHP 4 >= 4.3.0, PHP 5 < 5.1.0)

dio_tcsetattr — シリアルポートの端末属性とボーレートを設定する

### 説明

function 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 (true) {
        $data = dio_read($fd, 256);
        if ($data !== null && $data !== '') {
            echo $data;
        }
    }

    ?>

### 注意

> 注意: この関数は Windows 環境にはまだ実装されていません。

# dio_truncate

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_truncate — ファイル記述子 fd をオフセットバイトへ丸める

### 説明

function dio_truncate(resource `$fd`, int `$offset`): bool

dio_truncate() は、ファイルの大きさを 最大 `offset` バイトまでに丸めます。

ファイルがこのサイズより大きかった場合は、残りのデータは失われます。 ファイルがこのサイズより小さかった場合は、ファイルがそのままになるか 拡張されるかは未定義です。後者の場合、拡張された部分のデータはゼロと なります。

### パラメータ

`fd`

  dio_open() が返すファイル記述子。

`offset`

  オフセットのバイト数。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 注意

> 注意: この関数は Windows 環境にはまだ実装されていません。

# dio_write

(PHP 4 >= 4.2.0, PHP 5 < 5.1.0)

dio_write — オプションで丸め長さを指定してデータを書き込む

### 説明

function dio_write(resource `$fd`, string `$data`, int `$len` = 0): int

dio_write() は、`data` から最大 `len` バイトを ファイル `fd` に書き込みます。

### パラメータ

`fd`

  dio_open() が返すファイル記述子。

`data`

  書き込むデータ。

`len`

  書き込むデータのバイト長。指定しなかった場合は、データ全体を 指定したファイルに書き込みます。

### 戻り値

`fd` に書き込んだバイト数を返します。

### 参考

- dio_read() - ファイル記述子からバイトデータを読み込む

## 目次

- 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 — オプションで丸め長さを指定してデータを書き込む

- インストール/設定
  - インストール手順
  - リソース型
- 定義済み定数
- ダイレクト 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 — オプションで丸め長さを指定してデータを書き込む

# ディレクトリ

# 定義済み定数

`DIRECTORY_SEPARATOR` (string)
`PATH_SEPARATOR` (string)
  Windows の場合はセミコロン、それ以外の場合はコロンとなります。
`SCANDIR_SORT_ASCENDING` (int)
`SCANDIR_SORT_DESCENDING` (int)
`SCANDIR_SORT_NONE` (int)

# Directory クラス

(PHP 4, PHP 5, PHP 7, PHP 8)

## はじめに

Directory クラスのインスタンスを作るには dir() 関数を使います。new 演算子は使いません。

## クラス概要

final class Directory {
/* プロパティ */
public readonly string $path;
public readonly resource $handle;
/* メソッド */
public function close(): void
public function read(): string|false
public function rewind(): void
}

## プロパティ

path

  オープンされたディレクトリ。

handle

  readdir() や rewinddir()、 closedir() などのディレクトリ関数で使います。

## 変更履歴

バージョン | 説明
--- | ---
8.5.0 | このクラスは、final になりました。
8.1.0 | path と handle プロパティは、readonly になりました。

# Directory::close

(PHP 4, PHP 5, PHP 7, PHP 8)

Directory::close — ディレクトリハンドルをクローズする

### 説明

public function Directory::close(): void

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | 引数を取らなくなりました。 これより前のバージョンでは、 ディレクトリハンドルを引数に渡すことができました。

# Directory::read

(PHP 4, PHP 5, PHP 7, PHP 8)

Directory::read — ディレクトリハンドルからエントリを読み込む

### 説明

public function Directory::read(): string|false

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | 引数を取らなくなりました。 これより前のバージョンでは、 ディレクトリハンドルを引数に渡すことができました。

# Directory::rewind

(PHP 4, PHP 5, PHP 7, PHP 8)

Directory::rewind — ディレクトリハンドルを元に戻す

### 説明

public function Directory::rewind(): void

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | 引数を取らなくなりました。 これより前のバージョンでは、 ディレクトリハンドルを引数に渡すことができました。

## 目次

- Directory::close — ディレクトリハンドルをクローズする
- Directory::read — ディレクトリハンドルからエントリを読み込む
- Directory::rewind — ディレクトリハンドルを元に戻す

# ディレクトリ 関数

# 参考

dirname(), is_dir(), mkdir(), rmdir()等の関数については、 ファイルシステム の節を参照ください。

# chdir

(PHP 4, PHP 5, PHP 7, PHP 8)

chdir — ディレクトリを変更する

### 説明

function 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() - カレントのワーキングディレクトリを取得する

# chroot

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

chroot — ルートディレクトリを変更する

### 説明

function 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` を確認してください。

# closedir

(PHP 4, PHP 5, PHP 7, PHP 8)

closedir — ディレクトリハンドルをクローズする

### 説明

function closedir(?resource `$dir_handle` = `null`): void

`dir_handle` で指定したディレクトリのストリームをクローズします。

### パラメータ

`dir_handle`
  opendir() が事前にオープンした ディレクトリハンドルを示す resource。 `dir_handle` が `null` の場合は、 opendir() が最後にオープンしたものを使用します。

### 戻り値

値を返しません。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | `dir_handle` に `null` を指定することは、推奨されなくなりました。 代わりに、最後にオープンしたディレクトリハンドルを明示的に指定すべきです。
8.0.0 | `dir_handle` は、nullable になりました。

### 例

完全なサンプルコードは、 opendir() のドキュメントを参照ください。

### 参考

- opendir() - ディレクトリハンドルをオープンする
- readdir() - ディレクトリハンドルからエントリを読み込む
- rewinddir() - ディレクトリハンドルを元に戻す
- dir() - ディレクトリクラスのインスタンスを返す
- is_dir() - ファイルがディレクトリかどうかを調べる
- glob() - パターンにマッチするパス名を探す
- scandir() - 指定されたパスのファイルとディレクトリのリストを取得する

# dir

(PHP 4, PHP 5, PHP 7, PHP 8)

dir — ディレクトリクラスのインスタンスを返す

### 説明

function 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

### 注意

> 注意:

> 読み込みにより返されるディレクトリエントリの順番は、システムに依存します。

# getcwd

(PHP 4, PHP 5, PHP 7, PHP 8)

getcwd — カレントのワーキングディレクトリを取得する

### 説明

function 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() - ファイルのモードを変更する

# opendir

(PHP 4, PHP 5, PHP 7, PHP 8)

opendir — ディレクトリハンドルをオープンする

### 説明

function opendir(string `$directory`, ?resource `$context` = `null`): resource|false

ディレクトリハンドルをオープンします。このハンドルは、この後 closedir(), readdir(), rewinddir() 関数コールで使用されます。

### パラメータ

`directory`
  オープンするディレクトリのパス。
`context`
  `context` パラメータの詳細については マニュアルのストリーム を参照ください。

### 戻り値

成功した場合にディレクトリハンドルを返します。 失敗した場合に `false` を返します

### エラー / 例外

失敗したときは `E_WARNING` が発生します。

`directory` が有効なディレクトリでない場合、 権限の制限によりディレクトリがオープンできない場合、 またはファイルシステムのエラー時に起こりえます。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `context` は、nullable になりました。

### 例

例1 ディレクトリ中の全てのエントリを表示します。 ただし、特別な `.` と `..` ディレクトリはスキップします。

ファイル名やディレクトリ名は、 PHP が `false` と見なす文字列 (例: `"0"` という名前のディレクトリ) の可能性があり、かつ readdir() は全てのディレクトリエントリを読み取ったあとに `false` を返します。 そのため、PHP が `false` とみなすディレクトリ名と、 全てのディレクトリエントリを読み取ったことを適切に区別するためには、 比較演算子 `===` を使う必要があります。

    <?php

    if ($handle = opendir('/path/to/files')) {
        echo "Entries:\n";

        /* Correctly handling directory entries that may be considered falsy */
        while (false !== ($entry = readdir($handle))) {
            if ($entry === '.' || $entry === '..') {
                continue;
            }
            echo "$entry\n";
        }

        closedir($handle);
    }
    ?>

上の例の出力は、 たとえば以下のようになります。

    Entries:
    base
    en
    fr
    output.md
    test.php

### 参考

- readdir() - ディレクトリハンドルからエントリを読み込む
- rewinddir() - ディレクトリハンドルを元に戻す
- closedir() - ディレクトリハンドルをクローズする
- dir() - ディレクトリクラスのインスタンスを返す
- is_dir() - ファイルがディレクトリかどうかを調べる
- glob() - パターンにマッチするパス名を探す
- scandir() - 指定されたパスのファイルとディレクトリのリストを取得する

# readdir

(PHP 4, PHP 5, PHP 7, PHP 8)

readdir — ディレクトリハンドルからエントリを読み込む

### 説明

function readdir(?resource `$dir_handle` = `null`): string|false

ディレクトリから次のエントリの名前を返します。 エントリ名はファイルシステム上に格納されている順番で返されます。

### パラメータ

`dir_handle`
  opendir() が事前にオープンした ディレクトリハンドルを示す resource。 `dir_handle` が `null` の場合は、 opendir() が最後にオープンしたものを使用します。

### 戻り値

成功した場合にエントリ名、失敗した場合に `false` を返します。

警告

この関数は論理値 `false` を返す可能性がありますが、`false` として評価される値を返す可能性もあります。 詳細については 論理値の セクションを参照してください。この関数の返り値を調べるには ===演算子 を 使用してください。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | `dir_handle` に `null` を指定することは、推奨されなくなりました。 代わりに、最後にオープンしたディレクトリハンドルを明示的に指定すべきです。
8.0.0 | `dir_handle` は、nullable になりました

### 例

完全なサンプルコードは、 opendir() のドキュメントを参照ください。

### 参考

- opendir() - ディレクトリハンドルをオープンする
- rewinddir() - ディレクトリハンドルを元に戻す
- closedir() - ディレクトリハンドルをクローズする
- dir() - ディレクトリクラスのインスタンスを返す
- is_dir() - ファイルがディレクトリかどうかを調べる
- glob() - パターンにマッチするパス名を探す
- scandir() - 指定されたパスのファイルとディレクトリのリストを取得する

# rewinddir

(PHP 4, PHP 5, PHP 7, PHP 8)

rewinddir — ディレクトリハンドルを元に戻す

### 説明

function rewinddir(?resource `$dir_handle` = `null`): void

`dir_handle` で指定されたディレクトリの ストリームをディレクトリの先頭にリセットします。

### パラメータ

`dir_handle`
  opendir() が事前にオープンした ディレクトリハンドルを示す resource。 `dir_handle` が `null` の場合は、 opendir() が最後にオープンしたものを使用します。

### 戻り値

値を返しません。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | `dir_handle` に `null` を指定することは、推奨されなくなりました。 代わりに、最後にオープンしたディレクトリハンドルを明示的に指定すべきです。
8.0.0 | `dir_handle` は、nullable になりました。

### 例

完全なサンプルコードは、 opendir() のドキュメントを参照ください。

### 参考

- opendir() - ディレクトリハンドルをオープンする
- readdir() - ディレクトリハンドルからエントリを読み込む
- closedir() - ディレクトリハンドルをクローズする
- dir() - ディレクトリクラスのインスタンスを返す
- is_dir() - ファイルがディレクトリかどうかを調べる
- glob() - パターンにマッチするパス名を探す
- scandir() - 指定されたパスのファイルとディレクトリのリストを取得する

# scandir

(PHP 5, PHP 7, PHP 8)

scandir — 指定されたパスのファイルとディレクトリのリストを取得する

### 説明

function 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() - 配列を昇順にソートする

## 目次

- chdir — ディレクトリを変更する
- chroot — ルートディレクトリを変更する
- closedir — ディレクトリハンドルをクローズする
- dir — ディレクトリクラスのインスタンスを返す
- getcwd — カレントのワーキングディレクトリを取得する
- opendir — ディレクトリハンドルをオープンする
- readdir — ディレクトリハンドルからエントリを読み込む
- rewinddir — ディレクトリハンドルを元に戻す
- scandir — 指定されたパスのファイルとディレクトリのリストを取得する

- 定義済み定数
- Directory — Directory クラス
  - Directory::close — ディレクトリハンドルをクローズする
  - Directory::read — ディレクトリハンドルからエントリを読み込む
  - Directory::rewind — ディレクトリハンドルを元に戻す
- ディレクトリ 関数
  - chdir — ディレクトリを変更する
  - chroot — ルートディレクトリを変更する
  - closedir — ディレクトリハンドルをクローズする
  - dir — ディレクトリクラスのインスタンスを返す
  - getcwd — カレントのワーキングディレクトリを取得する
  - opendir — ディレクトリハンドルをオープンする
  - readdir — ディレクトリハンドルからエントリを読み込む
  - rewinddir — ディレクトリハンドルを元に戻す
  - scandir — 指定されたパスのファイルとディレクトリのリストを取得する

# ファイル情報

# はじめに

このモジュールの関数は、ファイル内の特定の位置から magic バイトシーケンスを見つけることで、 ファイルの content type とエンコーディングを推測します。 これは完全な手法ではありませんが、経験上かなりうまく動作しています。

# インストール/設定

## 目次

- インストール手順
- リソース型

## インストール手順

この拡張モジュールは、デフォルトで有効になっています。

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::buffer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_buffer -- finfo::buffer — 文字列バッファの情報を返す

### 説明

手続き型

function finfo_buffer(
finfo `$finfo`,
string `$string`,
int `$flags` = `FILEINFO_NONE`,
?resource `$context` = `null`
): string|false

オブジェクト指向型

public function finfo::buffer(string `$string`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

この関数は、バイナリデータの情報を文字列形式で返すために使用します。

### パラメータ

`finfo`
  finfo_open() が返す、finfo クラスのインスタンス。
`string`
  調べるファイルの内容。
`flags`
  ひとつあるいは複数のFileinfo 定数の組み合わせ。
`context`

### 戻り値

`string` のテキスト表現、あるいはエラーが発生した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | `context` パラメータは、無視されるため非推奨になりました。
8.1.0 | 引数 `finfo` は、finfo クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
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() - ファイルについての情報を返す

# finfo_close

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_close — fileinfo インスタンスを閉じる

警告

この関数は PHP 8.5.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function finfo_close(finfo `$finfo`): true

この関数は、PHP 7.4 までは finfo_open() がオープンしたインスタンスを閉じていましたが、 PHP 8.0 で finfo がリソースからオブジェクトに変換されて以降は何もしない関数（no-op）になっており、 PHP 8.5 で非推奨になりました。

### パラメータ

`finfo`
  finfo_open() が返す、finfo クラスのインスタンス。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | この関数は非推奨になりました。
8.5.0 | 戻り値の型が、`true` になりました。これより前のバージョンでは、bool でした。
8.1.0 | この関数は NOP（何もしない関数）になりました。
8.1.0 | 引数 `finfo` は、finfo クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

# finfo_file

# finfo::file

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_file -- finfo::file — ファイルについての情報を返す

### 説明

手続き型

function finfo_file(
finfo `$finfo`,
string `$filename`,
int `$flags` = `FILEINFO_NONE`,
?resource `$context` = `null`
): string|false

オブジェクト指向型

public function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
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() - 文字列バッファの情報を返す

# finfo_open

# finfo::__construct

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo_open -- finfo::__construct — 新しい fileinfo インスタンスを作成する

### 説明

手続き型

function finfo_open(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`): finfo|false

オブジェクト指向型 (コンストラクタ)

public function 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 クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。
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 インスタンスを閉じる

# 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 のオプションを設定する

### 説明

手続き型

function finfo_set_flags(finfo `$finfo`, int `$flags`): true

オブジェクト指向型

public function finfo::set_flags(int `$flags`): true

この関数は、さまざまな Fileinfo オプションを設定します。 finfo_open() やその他の Fileinfo 関数で、 オプションを直接指定することも可能です。

### パラメータ

`finfo`
  finfo_open() が返す、finfo クラスのインスタンス。
`flags`
  ひとつあるいは複数のFileinfo 定数の組み合わせ。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | 引数 `finfo` は、finfo クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

# mime_content_type

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mime_content_type — ファイルの MIME Content-type を検出する

### 説明

function 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_buffer — 文字列バッファの情報を返す
- finfo_close — fileinfo インスタンスを閉じる
- finfo_file — ファイルについての情報を返す
- finfo_open — 新しい fileinfo インスタンスを作成する
- finfo_set_flags — libmagic のオプションを設定する
- mime_content_type — ファイルの MIME Content-type を検出する

# finfo クラス

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

## はじめに

このクラスは、fileinfo 関数にオブジェクト指向のインターフェイスを提供します。

## クラス概要

class finfo {
/* メソッド */
public function __construct(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`)
public function buffer(string `$string`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false
public function file(string `$filename`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false
public function set_flags(int `$flags`): true
}

# finfo::buffer

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::buffer — finfo_buffer() のエイリアス

### 説明

public function finfo::buffer(string `$string`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

この関数は次の関数のエイリアスです。 finfo_buffer()

# finfo::__construct

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::__construct — finfo_open() のエイリアス

### 説明

public function finfo::__construct(int `$flags` = `FILEINFO_NONE`, ?string `$magic_database` = `null`)

この関数は次の関数のエイリアスです。 finfo_open()

### 変更履歴

バージョン | 説明
--- | ---
8.0.3 | `magic_database` は、nullable になりました。

# finfo::file

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::file — finfo_file() のエイリアス

### 説明

public function finfo::file(string `$filename`, int `$flags` = `FILEINFO_NONE`, ?resource `$context` = `null`): string|false

この関数は次の関数のエイリアスです。 finfo_file()

# finfo::set_flags

(PHP >= 5.3.0, PHP 7, PHP 8, PECL fileinfo >= 0.1.0)

finfo::set_flags — finfo_set_flags() のエイリアス

### 説明

public function finfo::set_flags(int `$flags`): true

この関数は次の関数のエイリアスです。 finfo_set_flags()

## 目次

- finfo::buffer — finfo_buffer() のエイリアス
- finfo::__construct — finfo_open のエイリアス
- finfo::file — finfo_file() のエイリアス
- finfo::set_flags — finfo_set_flags() のエイリアス

- インストール/設定
  - インストール手順
  - リソース型
- 定義済み定数
- 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() のエイリアス

# ファイルシステム

# はじめに

この拡張モジュールを構築するには外部ライブラリは必要ありませんが、 Linux 上で LFS (ラージファイル) をサポートする PHP を希望する場合は、 最新の glibc を入手し、次のコンパイラフラグ `-D_LARGEFILE_SOURCE -D_FILE_OFFSET_BITS=64` を付けて PHP をコンパイルする必要があります。

# インストール/設定

## 目次

- 実行時設定
- リソース型

## 実行時設定

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)

file() の `flags` パラメータで使える定数
`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)

  バイナリモード

  警告

  この定数は何の効果もありません。 PHP 8.1.0 以降は非推奨になっています。

`FILE_TEXT` (int)

  テキストモード

  警告

  この定数は何の効果もありません。 PHP 8.1.0 以降は非推奨になっています。

glob() の `flags` パラメータで使える定数
`GLOB_AVAILABLE_FLAGS` (int)
  全ての `GLOB_*` フラグの組み合わせ。以下と等しいです: `0` | `GLOB_BRACE` | `GLOB_MARK` | `GLOB_NOSORT` | `GLOB_NOCHECK` | `GLOB_NOESCAPE` | `GLOB_ERR` | `GLOB_ONLYDIR`
`GLOB_BRACE` (int)
  {a,b,c} を 'a', 'b', 'c' のいずれかにマッチするように展開します。

  > 注意: `GLOB_BRACE` は Solaris や Alpine Linux のような non GNU なシステムでは使えないことがあります。

`GLOB_ERR` (int)
  (ディレクトリが読み取れない場合のような) 読み取りエラーの場合に停止します。 デフォルトでは、エラーは無視されます。
`GLOB_MARK` (int)
  スラッシュ(Windows の場合はバックスラッシュ) を返されるディレクトリに個別に追加します。
`GLOB_NOCHECK` (int)
  マッチするファイルが見つからない場合に、検索パターンを返します。
`GLOB_NOESCAPE` (int)
  バックスラッシュは、メタキャラクタをクォートしません。
`GLOB_NOSORT` (int)
  ディレクトリ内に存在するかのように、ファイルを返します(ソートは行いません)。 このフラグを使わない場合、パス名はアルファベット順でソートされます。
`GLOB_ONLYDIR` (int)
  パターンにマッチするディレクトリエントリのみを返します。

pathinfo() の `flags` パラメータで使える定数
`PATHINFO_ALL` (int)
  pathinfo の全ての情報です。 連想配列として返されます。
`PATHINFO_DIRNAME` (int)
  ファイルのディレクトリパス
`PATHINFO_BASENAME` (int)
  ディレクトリ名、またはファイル名とその拡張子
`PATHINFO_EXTENSION` (int)
  ファイルの拡張子
`PATHINFO_FILENAME` (int)
  ファイル名（拡張子なし)またはディレクトリ名

parse_ini_file() と parse_ini_string() の `scanner_mode` パラメータで使える定数
`INI_SCANNER_NORMAL` (int)
  通常の INI スキャナモード
`INI_SCANNER_RAW` (int)
  生の INI スキャナモード
`INI_SCANNER_TYPED` (int)
  型つきの INI スキャナモード

fnmatch() の `flags` パラメータで使える定数
`FNM_NOESCAPE` (int)
  バックスラッシュのエスケープを無効にする。
`FNM_PATHNAME` (int)
  文字列中のスラッシュが、指定したパターン内のスラッシュにのみマッチする。
`FNM_PERIOD` (int)
  文字列の先頭のピリオドが、指定したパターン内のピリオドにのみマッチする。
`FNM_CASEFOLD` (int)
  大文字小文字を区別しないマッチを行う。GNU 拡張の一部。

PHP のファイルアップロード関連の定数
`UPLOAD_ERR_CANT_WRITE` (int)

  ファイルをディスクに書き込めませんでした。 この定数の値は `7` です。

`UPLOAD_ERR_EXTENSION` (int)

  PHP 拡張機能がファイルアップロードを停止させました。 PHP はどの拡張機能がファイルアップロードを止めたのかを検出する手段を提供していません。phpinfo() で表示される、ロード済みの拡張機能の一覧が手掛かりになるかもしれません。 この定数の値は `8` です。

`UPLOAD_ERR_FORM_SIZE` (int)

  アップロードされたファイルが、 HTML フォームで指定された MAX_FILE_SIZE を超えています。 この定数の値は `2` です。

`UPLOAD_ERR_INI_SIZE` (int)

  アップロードされたファイルが、 php.ini の upload_max_filesize を超えています。 この定数の値は `1` です。

`UPLOAD_ERR_NO_FILE` (int)

  アップロードされたファイルはありません。 この定数の値は `4` です。

`UPLOAD_ERR_NO_TMP_DIR` (int)

  テンポラリフォルダがありません。 この定数の値は `6` です。

`UPLOAD_ERR_OK` (int)

  エラーはありません。ファイルのアップロードは成功しました。 この定数の値は `0` です。

`UPLOAD_ERR_PARTIAL` (int)

  アップロードされたファイルは一部だけでした。 この定数の値は `3` です。

# ファイルシステム 関数

# 参考

関連する関数については、ディレクトリ およびプログラム実行の節を 参照ください。

リモートファイルとして使用することができる種々のURLラッパーの一覧 と説明については、サポートするプロトコル/ラッパーも参照ください。

# basename

(PHP 4, PHP 5, PHP 7, PHP 8)

basename — パスの最後にある名前の部分を返す

### 説明

function 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() - ファイルパスに関する情報を返す

# chgrp

(PHP 4, PHP 5, PHP 7, PHP 8)

chgrp — ファイルのグループを変更する

### 説明

function 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() - ファイルのモードを変更する

# chmod

(PHP 4, PHP 5, PHP 7, PHP 8)

chmod — ファイルのモードを変更する

### 説明

function 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() - ファイルに関する情報を取得する

# chown

(PHP 4, PHP 5, PHP 7, PHP 8)

chown — ファイルの所有者を変更する

### 説明

function 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() - ファイルのグループを変更する

# clearstatcache

(PHP 4, PHP 5, PHP 7, PHP 8)

clearstatcache — ファイルのステータスのキャッシュをクリアする

### 説明

function 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

# copy

(PHP 4, PHP 5, PHP 7, PHP 8)

copy — ファイルをコピーする

### 説明

function 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() - ファイルをリネームする
- マニュアルの ファイルアップロード処理

# delete

delete — unlink() か unset() を参照ください

### 説明

PHP には、delete というキーワードや関数は存在しません。 もしあなたがファイルを削除する方法を探してこのページにたどり着いたのなら、 unlink() を試してください。 ローカルスコープから変数を削除する場合は、 unset() を参照ください。

### 参考

- unlink() - ファイルを削除する
- unset() - 指定した変数の割当を解除する

# dirname

(PHP 4, PHP 5, PHP 7, PHP 8)

dirname — 親ディレクトリのパスを返す

### 説明

function 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 システムでは '.' を返します。
    ?>

### 例

例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() - 正規化された絶対パス名を返す

# disk_free_space

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

disk_free_space — ファイルシステムあるいはディスクパーティション上で利用可能な領域を返す

### 説明

function 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_total_space

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

disk_total_space — ファイルシステムあるいはディスクパーティションの全体サイズを返す

### 説明

function 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() - ファイルシステムあるいはディスクパーティション上で利用可能な領域を返す

# diskfreespace

(PHP 4, PHP 5, PHP 7, PHP 8)

diskfreespace — disk_free_space() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 disk_free_space().

# fclose

(PHP 4, PHP 5, PHP 7, PHP 8)

fclose — オープンされたファイルポインタをクローズする

### 説明

function fclose(resource `$stream`): bool

`stream`が指しているファイルをクローズします。

### パラメータ

`stream`

  ファイルポインタは有効なものでなければならず、また fopen()またはfsockopen() で正常にオープンされたファイルを指している必要があります。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 例

例1 シンプルな fclose() の例

    <?php

    $handle = fopen('somefile.txt', 'r');

    fclose($handle);

    ?>

### 参考

- fopen() - ファイルまたは URL をオープンする
- fsockopen() - インターネット接続もしくは Unix ドメインソケット接続をオープンする

# fdatasync

(PHP 8 >= 8.1.0)

fdatasync — データをファイルに同期する(但しメタデータは除く)

### 説明

function 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() - データをファイルに同期する(メタデータも含む)

# feof

(PHP 4, PHP 5, PHP 7, PHP 8)

feof — ファイルポインタがファイル終端に達しているかどうか調べる

### 説明

function 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);
    ?>

# fflush

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

fflush — 出力をファイルにフラッシュする

### 説明

function 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() - バイナリセーフなファイル書き込み処理

# fgetc

(PHP 4, PHP 5, PHP 7, PHP 8)

fgetc — ファイルポインタから1文字取り出す

### 説明

function 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 行取得する

# fgetcsv

(PHP 4, PHP 5, PHP 7, PHP 8)

fgetcsv — ファイルポインタから行を取得し、CSVフィールドを処理する

### 説明

function 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回連続させることで常にエスケープでき、 パース結果では単一の `enclosure` 文字になります。 `escape` 文字の動作は異なります: 入力中に `escape` と `enclosure` 文字の並びが出現した場合、 パース結果には両方の文字がそのまま残ります。 よって、デフォルトのパラメータの場合、 `"a""b","c\"d"` のような CSV の行は それぞれ `a"b` と `c\"d` にパースされます。

  警告

  PHP 8.4.0 以降では、`escape` のデフォルト値に依存することは非推奨となりました。 位置指定の引数か、名前付き引数 を使用して明示的に指定する必要があります。

警告

`escape` が空の文字列(`""`)以外に設定されているとき、 » RFC 4180 に準拠しない CSV が生成されたり、PHP の CSV 関数を介してラウンドトリップ(往復変換)でデータが壊れる可能性があります。 `escape`のデフォルト値は`"\\"` なので、明示的に空の文字列を指定することを推奨します。デフォルト値は、PHP 9.0 以降の将来のバージョンで変更予定です。

### 戻り値

読み込んだフィールドの内容を含む数値添字配列を返します。 失敗した場合に `false` を返します

> 注意:

> CSV ファイルの空行は null フィールドを一つだけ含む配列として返され、 エラーにはなりません。

> 注意: マッキントッシュコンピュータ上で作成されたファイルを読み込む際に、 `PHP` が行末を認識できないという問題が発生した場合、 実行時の設定オプションauto_detect_line_endings を有効にする必要が生じるかもしれません。

### エラー / 例外

`separator` または `enclosure` が 1 バイト長ではない場合、ValueError をスローします。

`escape` が 1 バイト長、または空文字列ではない場合、 ValueError をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `escape` のデフォルト値に依存することは、 非推奨になりました。
8.3.0 | 最後のフィールドが、 閉じられていないフィールド囲いこみ文字だけの場合、 null バイト 1 つの文字列ではなく、空文字列を返すようになりました。
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);
    }
    ?>

### 参考

- fputcsv() - 行を CSV 形式にフォーマットし、ファイルポインタに書き込む
- str_getcsv() - CSV 文字列をパースして配列に格納する
- SplFileObject::fgetcsv() - ファイルから行を取り出し CSV フィールドとして処理する
- SplFileObject::fputcsv() - フィールドの配列を CSV の行として書き出す
- SplFileObject::setCsvControl() - CSV の区切り文字、囲み文字、エスケープ文字をセットする
- SplFileObject::getCsvControl() - CSV の区切り、囲み文字、エスケープ文字を取得する
- explode() - 文字列を文字列により分割する
- file() - ファイル全体を読み込んで配列に格納する
- pack() - データをバイナリ文字列にパックする

# fgets

(PHP 4, PHP 5, PHP 7, PHP 8)

fgets — ファイルポインタから 1 行取得する

### 説明

function 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() - ストリームにタイムアウトを設定する

# fgetss

(PHP 4, PHP 5, PHP 7)

fgetss — ファイルポインタから 1 行取り出し、HTML タグを取り除く

警告

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

### 説明

function 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

# file

(PHP 4, PHP 5, PHP 7, PHP 8)

file — ファイル全体を読み込んで配列に格納する

### 説明

function 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 を有効にする必要が生じるかもしれません。

### エラー / 例外

PHP 8.3.0 以降では、`flags` に不正な値、 たとえば `FILE_APPEND` のような値が含まれていた場合、 ValueError がスローされます。

ファイルが存在しない場合は `E_WARNING` レベルのエラーが発生します。

### 変更履歴

バージョン | 説明
--- | ---
8.3.0 | `flags` に不正な値が含まれている場合、 ValueError がスローされるようになりました。

### 例

例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_exists

(PHP 4, PHP 5, PHP 7, PHP 8)

file_exists — ファイルまたはディレクトリが存在するかどうか調べる

### 説明

function 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_get_contents

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

file_get_contents — ファイルの内容を全て文字列に読み込む

### 説明

function 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 = [
      'http' => [
        'method' => "GET",
        'header' => "Accept-language: en\r\n" .
                    "Cookie: foo=bar",
      ]
    ];

    $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_put_contents

(PHP 5, PHP 7, PHP 8)

file_put_contents — データをファイルに書き込む

### 説明

function file_put_contents(
string `$filename`,
mixed `$data`,
int `$flags` = 0,
?resource `$context` = `null`
): int|false

この関数は、fopen()、fwrite()、 fclose() を続けてコールしてデータをファイルに書き込むのと等価です。

`filename` が存在しない場合はファイルを作成します。 存在する場合はそのファイルを上書きします。ただし `FILE_APPEND` フラグが設定されている場合は別です。

### パラメータ

`filename`

  データを書き込むファイルへのパス。

`data`

  書き込むデータ。string, array もしくは stream リソースのいずれかを指定可能です。

  `data` が stream リソースの場合は、 ストリームのバッファに残っている内容が指定したファイルにコピーされます。 これは、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() - ストリームコンテキストを作成する

# fileatime

(PHP 4, PHP 5, PHP 7, PHP 8)

fileatime — ファイルの最終アクセス時刻を取得する

### 説明

function 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タイムスタンプを書式化する

# filectime

(PHP 4, PHP 5, PHP 7, PHP 8)

filectime — ファイルの inode 変更時刻を取得する

### 説明

function 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() - ファイルの更新時刻を取得する

# filegroup

(PHP 4, PHP 5, PHP 7, PHP 8)

filegroup — ファイルのグループを取得する

### 説明

function 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 を有するグループに関する情報を返す

# fileinode

(PHP 4, PHP 5, PHP 7, PHP 8)

fileinode — ファイルの inode を取得する

### 説明

function 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() - ファイルに関する情報を取得する

# filemtime

(PHP 4, PHP 5, PHP 7, PHP 8)

filemtime — ファイルの更新時刻を取得する

### 説明

function 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() - 最終更新時刻を取得する

# fileowner

(PHP 4, PHP 5, PHP 7, PHP 8)

fileowner — ファイルの所有者を取得する

### 説明

function 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 のユーザーに関する情報を返す

# fileperms

(PHP 4, PHP 5, PHP 7, PHP 8)

fileperms — ファイルのパーミッションを取得する

### 説明

function 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() - ファイルに関する情報を取得する

# filesize

(PHP 4, PHP 5, PHP 7, PHP 8)

filesize — ファイルのサイズを取得する

### 説明

function 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() - ファイルまたはディレクトリが存在するかどうか調べる

# filetype

(PHP 4, PHP 5, PHP 7, PHP 8)

filetype — ファイルタイプを取得する

### 説明

function 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() - ファイルに関する情報を取得する

# flock

(PHP 4, PHP 5, PHP 7, PHP 8)

flock — 汎用のファイルロックを行う

### 説明

function 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);      // ファイルを切り詰めます
        rewind($fp);
        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 では、 ロックするプロセスが同じファイルを二回オープンする場合、 ファイルをアンロックするまで二番目のハンドルではアクセスできません。

# fnmatch

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

fnmatch — ファイル名がパターンにマッチするか調べる

### 説明

function 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() - フォーマットされた文字列を返す

# fopen

(PHP 4, PHP 5, PHP 7, PHP 8)

fopen — ファイルまたは URL をオープンする

### 説明

function 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 でのみ利用可能です。
  `'n'` | オープンされたファイル記述子に non-blocking フラグを設定します。 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

# fpassthru

(PHP 4, PHP 5, PHP 7, PHP 8)

fpassthru — ファイルポインタ上に残っているすべてのデータを出力する

### 説明

function 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 ドメインソケット接続をオープンする

# fputcsv

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

fputcsv — 行を CSV 形式にフォーマットし、ファイルポインタに書き込む

### 説明

function fputcsv(
resource `$stream`,
array `$fields`,
string `$separator` = ",",
string `$enclosure` = "\"",
string `$escape` = "\\",
string `$eol` = "\n"
): int|false

fputcsv() は、行（`fields` 配列として渡されたもの）を CSV としてフォーマットし、それを、 指定した `stream` に書き込みます (いちばん最後に `eol` を追加します)。

### パラメータ

`stream`
  ファイルポインタは、有効なファイルポインタである必要があり、 fopen() または fsockopen() で正常にオープンされた （そしてまだ fclose() でクローズされていない） ファイルを指している必要があります。
`fields`

  文字列の配列。

`separator`

  `separator` パラメータで、フィールドのデリミタを設定します。 シングルバイト文字 1 文字のみでなければなりません。

`enclosure`

  オプションの `enclosure` パラメータで、フィールド囲いこみ文字を設定します。 シングルバイト文字 1 文字のみでなければなりません。

`escape`

  オプションの `escape` パラメータで、エスケープ文字を設定します。 シングルバイト文字 1 文字のみ、または空文字列でなければなりません。 空文字列(`""`) を指定すると、(RFC 4180 に準拠していない) 独自仕様のエスケープ機構が無効になります。

  警告

  入力ストリームにおいて、`enclosure` 文字は クォートされた文字列の中で2回連続させることで常にエスケープでき、 パース結果では単一の `enclosure` 文字になります。 `escape` 文字の動作は異なります: 入力中に `escape` と `enclosure` 文字の並びが出現した場合、 パース結果には両方の文字がそのまま残ります。 よって、デフォルトのパラメータの場合、 `"a""b","c\"d"` のような CSV の行は それぞれ `a"b` と `c\"d` にパースされます。

  警告

  PHP 8.4.0 以降では、`escape` のデフォルト値に依存することは非推奨となりました。 位置指定の引数か、名前付き引数 を使用して明示的に指定する必要があります。

`eol`

  `eol` は、 カスタムの行末シーケンスを設定するオプションの引数です。

警告

`escape` が空の文字列(`""`)以外に設定されているとき、 » RFC 4180 に準拠しない CSV が生成されたり、PHP の CSV 関数を介してラウンドトリップ(往復変換)でデータが壊れる可能性があります。 `escape`のデフォルト値は`"\\"` なので、明示的に空の文字列を指定することを推奨します。デフォルト値は、PHP 9.0 以降の将来のバージョンで変更予定です。

> 注意:

> `enclosure` がフィールド内に含まれる場合は、同じ文字を二度続けることでエスケープします。 ただし、その直前に `escape` がある場合は別です。

### 戻り値

書き込んだ文字列の長さを返します。失敗した場合に `false` を返します。

### エラー / 例外

`separator` または `enclosure` が 1 バイト長ではない場合、ValueError をスローします。

`escape` が 1 バイト長、または空文字列ではない場合、 ValueError をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `escape` のデフォルト値に依存することは、 非推奨になりました。
8.1.0 | オプションの引数 `eol` が追加されました。
7.4.0 | `escape` パラメータが、 (RFC 4180 に準拠していない) 独自仕様のエスケープ機構を無効にするため、 空文字列を受け入れるようになりました。

### 例

例1 fputcsv() の例

    <?php

    $list = [
        ['aaa', 'bbb', 'ccc', 'dddd'],
        ['123', '456', '789'],
        ['"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"""

### 参考

- fgetcsv() - ファイルポインタから行を取得し、CSVフィールドを処理する
- str_getcsv() - CSV 文字列をパースして配列に格納する
- SplFileObject::fgetcsv() - ファイルから行を取り出し CSV フィールドとして処理する
- SplFileObject::fputcsv() - フィールドの配列を CSV の行として書き出す
- SplFileObject::setCsvControl() - CSV の区切り文字、囲み文字、エスケープ文字をセットする
- SplFileObject::getCsvControl() - CSV の区切り、囲み文字、エスケープ文字を取得する

# fputs

(PHP 4, PHP 5, PHP 7, PHP 8)

fputs — fwrite() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 fwrite().

# fread

(PHP 4, PHP 5, PHP 7, PHP 8)

fread — バイナリセーフなファイルの読み込み

### 説明

function 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() - バイナリ文字列からデータを切り出す

# fscanf

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

fscanf — フォーマットに基づきファイルからの入力を処理する

### 説明

function 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` が返されます。

オプションのパラメータを使用していて、 いずれかの値がパースされる前に `stream` から読み込んだ入力の終端に達した場合は、 `-1` が返されます。

### 例

例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() - フォーマットされた文字列を返す

# fseek

(PHP 4, PHP 5, PHP 7, PHP 8)

fseek — ファイルポインタを移動する

### 説明

function 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` を返します。

警告

この関数は、同じ名前のC言語の関数を真似る目的で作られています。 PHP で期待される戻り値と異なることに注意してください。

### 例

例1 fseek() の例

    <?php

    $fp = fopen('somefile.txt', 'r');

    // データを読み込む
    $data = fgets($fp, 4096);

    // ファイルの先頭に移動する。
    // rewind($fp); と等価。
    fseek($fp, 0);

    ?>

### 注意

> 注意:

> 追加モード (`a` あるいは `a+`) でファイルをオープンした場合、 ファイル位置によらず、ファイルに書き込むあらゆるデータが追加されます。また fseek() の結果は未定義となります。

> 注意:

> すべてのストリームがシーク処理に対応しているわけではありません。 シークに対応していないストリームで現在位置から前方へのシークを行うには、 データを読み込んでそれを捨てていくしかありません。それ以外のやり方は失敗します。

### 参考

- ftell() - ファイルの読み書き用ポインタの現在位置を返す
- rewind() - ファイルポインタの位置を先頭に戻す

# fstat

(PHP 4, PHP 5, PHP 7, PHP 8)

fstat — オープンしたファイルポインタからファイルに関する情報を取得する

### 説明

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

### 注意

> 注意: この関数では、 リモートファイル を 使用することはできません。これは、処理されるファイルがサーバーの ファイルシステムによりアクセスできる必要があるためです。

# fsync

(PHP 8 >= 8.1.0)

fsync — データをファイルに同期する(メタデータも含む)

### 説明

function 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() - 出力をファイルにフラッシュする

# ftell

(PHP 4, PHP 5, PHP 7, PHP 8)

ftell — ファイルの読み書き用ポインタの現在位置を返す

### 説明

function 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() - ファイルポインタの位置を先頭に戻す

# ftruncate

(PHP 4, PHP 5, PHP 7, PHP 8)

ftruncate — ファイルを指定した長さに丸める

### 説明

function 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() - ファイルポインタを移動する

# fwrite

(PHP 4, PHP 5, PHP 7, PHP 8)

fwrite — バイナリセーフなファイル書き込み処理

### 説明

function 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() - データをバイナリ文字列にパックする

# glob

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

glob — パターンにマッチするパス名を探す

### 説明

function glob(string `$pattern`, int `$flags` = 0): array|false

glob() 関数は libc の glob() 関数で使われるルールに基づいて `pattern` にマッチする全てのパス名を検索します。 ルールは、一般のシェルで使われるルールと似ています。

Unix システムと macOS での振る舞いは、 システムの glob() の実装によって決まります。 Windows の実装は、POSIX 1003.2 の glob() の定義を満たしており、 範囲を否定する規約 `[!...]` を扱うための拡張も含んでいます。

### パラメータ

`pattern`

  パターン。チルダの展開やパラメータ置換は行いません。

  特殊文字は以下のとおりです:

  - `*` - ゼロ文字以上の文字にマッチします。
  - `?` - 正確に(任意の)一文字にだけマッチします。
  - `[...]` - グループ化された文字のうち、一文字にマッチします。 はじめの文字が `!` だった場合、 グループにないあらゆる文字にマッチします。
  - `{a,b,c}` - `GLOB_BRACE` フラグを使った場合に、コンマで区切った文字列のグループのうち、ひとつにマッチします。
  - `\` - 次に来る文字をエスケープします。 但し、`GLOB_NOESCAPE` が使われている場合は除きます。
`flags`

  `GLOB_*` 定数のいずれか

### 戻り値

マッチするファイル／ディレクトリを含む配列を返します。 マッチするファイルがなかった場合には空の配列、 そして失敗した場合には `false` を返します。 `GLOB_NOSORT` を使わない限り、 名前はアルファベット順にソートされます。

### 例

例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

例2 もっと複雑なパターンを使う例

    <?php
    foreach (glob("path/*/*.{txt,md}", \GLOB_BRACE) as $filename) {
        echo "$filename\n";
    }
    ?>

上の例の出力は、 たとえば以下のようになります。

    path/docs/mailinglist-rules.md
    path/docs/README.md
    path/docs/release-process.md
    path/pear/install-pear.txt
    path/Zend/README.md

### 注意

> 注意: この関数では、 リモートファイル を 使用することはできません。これは、処理されるファイルがサーバーの ファイルシステムによりアクセスできる必要があるためです。

> 注意: この関数が使用できないシステムも存在します (例: 昔の Sun OS など)。

### 参考

- opendir() - ディレクトリハンドルをオープンする
- readdir() - ディレクトリハンドルからエントリを読み込む
- closedir() - ディレクトリハンドルをクローズする
- fnmatch() - ファイル名がパターンにマッチするか調べる

# is_dir

(PHP 4, PHP 5, PHP 7, PHP 8)

is_dir — ファイルがディレクトリかどうかを調べる

### 説明

function 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_executable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_executable — ファイルが実行可能かどうかを調べる

### 説明

function 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_file

(PHP 4, PHP 5, PHP 7, PHP 8)

is_file — 通常ファイルかどうかを調べる

### 説明

function is_file(string `$filename`): bool

指定したファイルが通常のファイルかどうかを調べます。 `filename` がシンボリックリンクの場合、 リンクは解決され、それが参照しているファイルの情報を返します。

### パラメータ

`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_link

(PHP 4, PHP 5, PHP 7, PHP 8)

is_link — ファイルがシンボリックリンクかどうかを調べる

### 説明

function 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() - シンボリックリンク先を返す
- symlink() - シンボリックリンクを作成する

# is_readable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_readable — ファイルが存在し、読み込み可能であるかどうかを知る

### 説明

function 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 行取得する

# is_uploaded_file

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

is_uploaded_file — HTTP POST でアップロードされたファイルかどうかを調べる

### 説明

function 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_writable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_writable — ファイルが書き込み可能かどうかを調べる

### 説明

function 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_writeable

(PHP 4, PHP 5, PHP 7, PHP 8)

is_writeable — is_writable() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 is_writable().

# lchgrp

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

lchgrp — シンボリックリンクのグループ所有権を変更する

### 説明

function 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() - ファイルのモードを変更する

# lchown

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

lchown — シンボリックリンクの所有者を変更する

### 説明

function 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() - ファイルのモードを変更する

# link

(PHP 4, PHP 5, PHP 7, PHP 8)

link — ハードリンクを作成する

### 説明

function 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() - ファイルを削除する

# linkinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

linkinfo — リンクに関する情報を取得する

### 説明

function 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() - シンボリックリンク先を返す

# lstat

(PHP 4, PHP 5, PHP 7, PHP 8)

lstat — ファイルあるいはシンボリックリンクの情報を取得する

### 説明

function 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() - ファイルに関する情報を取得する

# mkdir

(PHP 4, PHP 5, PHP 7, PHP 8)

mkdir — ディレクトリを作る

### 説明

function 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 を変更する

# move_uploaded_file

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

move_uploaded_file — アップロードされたファイルを新しい位置に移動する

### 説明

function 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() - ファイルをリネームする
- 簡単な使用例については ファイルアップロードの処理

# parse_ini_file

(PHP 4, PHP 5, PHP 7, PHP 8)

parse_ini_file — 設定ファイルをパースする

### 説明

function 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 の構造と同じです。

警告

この関数は、信頼できない入力に対して使用してはいけません。 ただし、`scanner_mode` が `INI_SCANNER_RAW` の場合を除きます。 パース済みの出力には、データベースパスワードを保持する定数など、 機密性の高い定数の値が含まれる可能性があるためです。

### パラメータ

`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_string

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

parse_ini_string — 設定文字列をパースする

### 説明

function 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 の構造と同じです。

警告

この関数は、信頼できない入力に対して使用してはいけません。 ただし、`scanner_mode` が `INI_SCANNER_RAW` の場合を除きます。 パース済みの出力には、データベースパスワードを保持する定数など、 機密性の高い定数の値が含まれる可能性があるためです。

### パラメータ

`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() - 設定ファイルをパースする

# pathinfo

(PHP 4 >= 4.0.3, PHP 5, PHP 7, PHP 8)

pathinfo — ファイルパスに関する情報を返す

### 説明

function 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() - 正規化された絶対パス名を返す

# pclose

(PHP 4, PHP 5, PHP 7, PHP 8)

pclose — プロセスのファイルポインタをクローズする

### 説明

function 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() - プロセスへのファイルポインタをオープンする

# popen

(PHP 4, PHP 5, PHP 7, PHP 8)

popen — プロセスへのファイルポインタをオープンする

### 説明

function 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() - コマンドを実行し、入出力用にファイルポインタを開く

# readfile

(PHP 4, PHP 5, PHP 7, PHP 8)

readfile — ファイルを出力する

### 説明

function 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() - ファイルの内容を全て文字列に読み込む
- サポートするプロトコル/ラッパー

# readlink

(PHP 4, PHP 5, PHP 7, PHP 8)

readlink — シンボリックリンク先を返す

### 説明

function 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() - リンクに関する情報を取得する

# realpath

(PHP 4, PHP 5, PHP 7, PHP 8)

realpath — 正規化された絶対パス名を返す

### 説明

function 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_cache_get

(PHP 5 >= 5.3.2, PHP 7, PHP 8)

realpath_cache_get — realpath キャッシュ・エントリーを取得

### 説明

function 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_cache_size

(PHP 5 >= 5.3.2, PHP 7, PHP 8)

realpath_cache_size — realpath キャッシュサイズを取得

### 説明

function 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

# rename

(PHP 4, PHP 5, PHP 7, PHP 8)

rename — ファイルをリネームする

### 説明

function 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() - アップロードされたファイルを新しい位置に移動する

# rewind

(PHP 4, PHP 5, PHP 7, PHP 8)

rewind — ファイルポインタの位置を先頭に戻す

### 説明

function 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() - バイナリセーフなファイル書き込み処理

# rmdir

(PHP 4, PHP 5, PHP 7, PHP 8)

rmdir — ディレクトリを削除する

### 説明

function 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() - ファイルを削除する

# set_file_buffer

(PHP 4, PHP 5, PHP 7, PHP 8)

set_file_buffer — stream_set_write_buffer() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 stream_set_write_buffer().

# stat

(PHP 4, PHP 5, PHP 7, PHP 8)

stat — ファイルに関する情報を取得する

### 説明

function 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

# symlink

(PHP 4, PHP 5, PHP 7, PHP 8)

symlink — シンボリックリンクを作成する

### 説明

function 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);
    ?>

### 参考

- is_link() - ファイルがシンボリックリンクかどうかを調べる
- link() - ハードリンクを作成する
- readlink() - シンボリックリンク先を返す
- linkinfo() - リンクに関する情報を取得する
- unlink() - ファイルを削除する

# tempnam

(PHP 4, PHP 5, PHP 7, PHP 8)

tempnam — 一意なファイル名を持つファイルを作成する

### 説明

function tempnam(string `$directory`, string `$prefix`): string|false

一意なファイル名を持つファイルを、パーミッションを 0600 に設定し、 指定したディレクトリに作成します。 指定したディレクトリが存在しない場合やディレクトリに書き込めない場合は、tempnam() はシステムのテンポラリディレクトリにファイルを生成し、 そのファイルへのフルパスを (名前を含めて) 返すことがあります。

### パラメータ

`directory`

  テンポラリファイルを作成したいディレクトリ。

`prefix`

  作成されるテンポラリファイルのプレフィックス。

  > 注意: プレフィックスの最初の63文字のみを使用し、残りは無視されます。 Windows では、プレフィックスの最初の 3 文字のみを使用します。

### 戻り値

新しいテンポラリファイル名 (パスを含む) を返し、失敗した場合には `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | tempnam() が作成するファイルの名前は、 以前より13バイト長くなりました。 総合的な長さは引き続きプラットフォーム依存です。
7.1.0 | tempnam() は、 システムのテンポラリディレクトリにフォールバックした場合に notice を発行するようになりました。

### 例

例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() - ファイルを削除する

# tmpfile

(PHP 4, PHP 5, PHP 7, PHP 8)

tmpfile — テンポラリファイルを作成する

### 説明

function 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() - 一時ファイル用に使用されるディレクトリのパスを返す

# touch

(PHP 4, PHP 5, PHP 7, PHP 8)

touch — ファイルの最終アクセス時刻および最終更新日をセットする

### 説明

function 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

(PHP 4, PHP 5, PHP 7, PHP 8)

umask — 現在の umask を変更する

### 説明

function 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 サーバー自身の予期しない動作を引き起こす原因になる可能性があります。

# unlink

(PHP 4, PHP 5, PHP 7, PHP 8)

unlink — ファイルを削除する

### 説明

function 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() - ディレクトリを削除する

## 目次

- 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 — ファイルを削除する

- インストール/設定
  - 実行時設定
  - リソース型
- 定義済み定数
- ファイルシステム 関数
  - 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 — ファイルを削除する

# 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 イベントの読み込みを置き換えるものです。

# インストール/設定

## 目次

- インストール/設定
- リソース型

## インストール/設定

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/inotify.

## リソース型

この拡張モジュールでは、 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

(PECL inotify >= 0.1.2)

inotify_add_watch — 初期化済みの inotify インスタンスに監視対象を追加する

### 説明

function 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_init

(PECL inotify >= 0.1.2)

inotify_init — inotify インスタンスを初期化する

### 説明

function 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_queue_len

(PECL inotify >= 0.1.2)

inotify_queue_len — 待機中のイベントがある場合に正の数を返す

### 説明

function 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_read

(PECL inotify >= 0.1.2)

inotify_read — inotify インスタンスからイベントを読み込む

### 説明

function 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_rm_watch

(PECL inotify >= 0.1.2)

inotify_rm_watch — 既存の監視を inotify インスタンスから削除する

### 説明

function 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 インスタンスを初期化する

## 目次

- inotify_add_watch — 初期化済みの inotify インスタンスに監視対象を追加する
- inotify_init — inotify インスタンスを初期化する
- inotify_queue_len — 待機中のイベントがある場合に正の数を返す
- inotify_read — inotify インスタンスからイベントを読み込む
- inotify_rm_watch — 既存の監視を inotify インスタンスから削除する

- インストール/設定
  - インストール/設定
  - リソース型
- 定義済み定数
- Inotify 関数
  - inotify_add_watch — 初期化済みの inotify インスタンスに監視対象を追加する
  - inotify_init — inotify インスタンスを初期化する
  - inotify_queue_len — 待機中のイベントがある場合に正の数を返す
  - inotify_read — inotify インスタンスからイベントを読み込む
  - inotify_rm_watch — 既存の監視を inotify インスタンスから削除する

# xattr

# はじめに

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

(PECL xattr >= 0.9.0)

xattr_get — 拡張属性を取得する

### 説明

function xattr_get(string `$filename`, string `$name`, int `$flags` = 0): string|false

この関数は、ファイルの拡張属性の値を取得します。

拡張属性には二種類の異なる名前空間、つまり、ユーザーとルートがあります。 ユーザー名前空間は、すべてのユーザーで利用可能ですが、ルート名前空間は、ルート権限を有するユーザーのみ利用可能です。 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_list

(PECL xattr >= 0.9.0)

xattr_list — 拡張属性の一覧を取得する

### 説明

function 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 ($user_attributes as $attr_name) {
        printf("%s\n", $attr_name);
    }

    ?>

### 参考

- xattr_get() - 拡張属性を取得する

# xattr_remove

(PECL xattr >= 0.9.0)

xattr_remove — 拡張属性を削除する

### 説明

function 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_set

(PECL xattr >= 0.9.0)

xattr_set — 拡張属性を設定する

### 説明

function 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_supported

(PECL xattr >= 1.0.0)

xattr_supported — ファイルシステムが拡張属性をサポートしているかどうかを調べる

### 説明

function 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() - 拡張属性の一覧を取得する

## 目次

- xattr_get — 拡張属性を取得する
- xattr_list — 拡張属性の一覧を取得する
- xattr_remove — 拡張属性を削除する
- xattr_set — 拡張属性を設定する
- xattr_supported — ファイルシステムが拡張属性をサポートしているかどうかを調べる

- インストール/設定
  - 要件
  - インストール手順
- 定義済み定数
- xattr 関数
  - xattr_get — 拡張属性を取得する
  - xattr_list — 拡張属性の一覧を取得する
  - xattr_remove — 拡張属性を削除する
  - xattr_set — 拡張属性を設定する
  - xattr_supported — ファイルシステムが拡張属性をサポートしているかどうかを調べる

# xdiff

# はじめに

xdiff 拡張モジュールを使用すると、 異なるリビジョンのファイルの差分を含むパッチファイルの作成やその適用ができるようになります。

この拡張モジュールは、文字列に対する操作とファイルに対する操作の 2 通りのモードに対応しています。また、unified 形式とバイナリ形式の 2 通りのパッチフォーマットに対応しています。 Unified 形式のパッチはテキストファイルに最適です。 人間が読みやすい形式であることから、容易にレビューできるようになります。 アーカイブファイルや画像ファイルなどのバイナリファイルの場合は バイナリ形式を使うのがよいでしょう。この形式はバイナリセーフであり、 非表示文字も扱えるからです。

バージョン 1.5.0 以降、バイナリ形式のパッチを作成するための方法が 2 通り用意されています。新しい関数である xdiff_string_rabdiff() と xdiff_file_rabdiff() の出力は、 以前の関数と互換性のあるものとなります。 しかし、より高速でよりサイズが小さいものとなります。 どのようにバイナリパッチを作成しているのかや これまでの関数とどのように違うのかといった情報については » libxdiff のウェブサイトを参照ください。

この拡張モジュールは、libxdiff を用いてこれらの機能を実装しています。 詳細な情報は » http://www.xmailserver.org/xdiff-lib.html を参照ください。

# インストール/設定

## 目次

- 要件
- インストール手順

## 要件

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 拡張モジュールの Windows バイナリ (DLL ファイル) は、PECL のウェブサイトから取得できます。

# 定義済み定数

以下の定数が定義されています。 この関数の拡張モジュールが 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

(PECL xdiff >= 1.5.0)

xdiff_file_bdiff — 2 つのファイルのバイナリ diff を作成する

### 説明

function 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 形式のパッチを適用する

# xdiff_file_bdiff_size

(PECL xdiff >= 1.5.0)

xdiff_file_bdiff_size — バイナリ diff を適用して作成するファイルのサイズを読み込む

### 説明

function 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 形式のパッチを適用する

# xdiff_file_bpatch

(PECL xdiff >= 1.5.0)

xdiff_file_bpatch — ファイルにバイナリ diff 形式のパッチを適用する

### 説明

function 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 アルゴリズムで作成する

# xdiff_file_diff

(PECL xdiff >= 0.2.0)

xdiff_file_diff — 2 つのファイルの unified diff を作成する

### 説明

function 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_diff_binary

(PECL xdiff >= 0.2.0)

xdiff_file_diff_binary — xdiff_file_bdiff() のエイリアス

### 説明

function 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 形式のパッチを適用する

# xdiff_file_merge3

(PECL xdiff >= 0.2.0)

xdiff_file_merge3 — 3 つのファイルをひとつに統合する

### 説明

function 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 つの文字列をひとつに統合する

# xdiff_file_patch

(PECL xdiff >= 0.2.0)

xdiff_file_patch — ファイルに unified diff 形式のパッチを適用する

### 説明

function 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_patch_binary

(PECL xdiff >= 0.2.0)

xdiff_file_patch_binary — xdiff_file_bpatch() のエイリアス

### 説明

function 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 のエイリアス

# xdiff_file_rabdiff

(PECL xdiff >= 1.5.0)

xdiff_file_rabdiff — 2 つのファイルのバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する

### 説明

function 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 形式のパッチを適用する

# xdiff_string_bdiff

(PECL xdiff >= 1.5.0)

xdiff_string_bdiff — 2 つの文字列のバイナリ diff を作成する

### 説明

function 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 形式のパッチを適用する

# xdiff_string_bdiff_size

(PECL xdiff >= 1.5.0)

xdiff_string_bdiff_size — バイナリ diff を適用して作成するファイルのサイズを読み込む

### 説明

function 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 形式のパッチを適用する

# xdiff_string_bpatch

(PECL xdiff >= 1.5.0)

xdiff_string_bpatch — 文字列にバイナリ diff 形式のパッチを適用する

### 説明

function 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 アルゴリズムで作成する

# xdiff_string_diff

(PECL xdiff >= 0.2.0)

xdiff_string_diff — 2 つの文字列の unified diff を作成する

### 説明

function 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_diff_binary

(PECL xdiff >= 0.2.0)

xdiff_string_diff_binary — xdiff_string_bdiff() のエイリアス

### 説明

function 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 形式のパッチを適用する

# xdiff_string_merge3

(PECL xdiff >= 0.2.0)

xdiff_string_merge3 — 3 つの文字列をひとつに統合する

### 説明

function 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 つのファイルをひとつに統合する

# xdiff_string_patch

(PECL xdiff >= 0.2.0)

xdiff_string_patch — 文字列に unified diff 形式のパッチを適用する

### 説明

function 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_patch_binary

(PECL xdiff >= 0.2.0)

xdiff_string_patch_binary — xdiff_string_bpatch() のエイリアス

### 説明

function 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 アルゴリズムで作成する

# xdiff_string_rabdiff

(PECL xdiff >= 1.5.0)

xdiff_string_rabdiff — 2 つの文字列のバイナリ diff を、Rabin の polynomial fingerprinting アルゴリズムで作成する

### 説明

function xdiff_string_rabdiff(string `$old_data`, string `$new_data`): string|false

ふたつの文字列のバイナリ diff を生成します。 » libxdiff によって実装された Rabin の polynomial fingerprinting アルゴリズムを使用します。 この関数と xdiff_string_bdiff() との違いは、 使用するアルゴリズムです。この関数のほうが実行速度が速く、 より小さな diff を生成します。 また、パッチを適用する際に用いる xdiff_string_bpatch() や xdiff_file_bpatch() と完全な互換性があります。

この関数はテキストファイルとバイナリファイルの両方に適用可能です。 生成された diff データは後に適用することで、 古いバージョンから新しいバージョンを再構築できます。

アルゴリズムの詳細は、 » libxdiff documentation を参照ください。

### パラメータ

`old_data`

  "旧" バイナリデータを含む最初の文字列

`new_data`

  "新" バイナリデータを含む 2 番目の文字列

### 戻り値

"旧" データと "新" データの差分を含むバイナリ diff 文字列を返します。 失敗した場合に `false` を返します

### 例

例1 2つの文字列間のバイナリ diff を作成する

    <?php
    $old = file_get_contents('file_v1.txt');
    $new = file_get_contents('file_v2.txt');

    $diff = xdiff_string_rabdiff($old, $new);
    file_put_contents('patch.rdiff', $diff);
    ?>

### 参考

- xdiff_string_bdiff() - 2 つの文字列のバイナリ diff を作成する
- xdiff_string_bpatch() - 文字列にバイナリ diff 形式のパッチを適用する
- xdiff_file_bpatch() - ファイルにバイナリ diff 形式のパッチを適用する

## 目次

- 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 関数
  - 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 アルゴリズムで作成する

- ダイレクト IO
  - インストール/設定
  - 定義済み定数
  - ダイレクト IO 関数
- ディレクトリ
  - 定義済み定数
  - Directory — Directory クラス
  - ディレクトリ 関数
- Fileinfo — ファイル情報
  - インストール/設定
  - 定義済み定数
  - Fileinfo 関数
  - finfo — finfo クラス
- ファイルシステム
  - インストール/設定
  - 定義済み定数
  - ファイルシステム 関数
- Inotify
  - インストール/設定
  - 定義済み定数
  - Inotify 関数
- xattr
  - インストール/設定
  - 定義済み定数
  - xattr 関数
- xdiff
  - インストール/設定
  - 定義済み定数
  - xdiff 関数

# 自然言語および文字エンコーディング

# Enchant スペリングライブラリ

# はじめに

Enchant は、» Enchant ライブラリ を PHP から利用できるようにしたものです。Enchant は、 すべてのスペリングライブラリの上位に位置するもので、 統一された操作性を提供します。 また、各ライブラリが搭載していないかもしれない機能についても実装しています。 すべての機能が "動作します"。 いろんな意味で、あらゆる意味で "動作しています"。

Enchant は以下のバックエンドをサポートしています。

- `Aspell/Pspell (Ispell の後継です)`
- `Ispell (昔からあり、デファクトスタンダードとされています)`
- `MySpell/Hunspell (OOo プロジェクトや Mozilla が使用しています)`
- `Uspell (イディッシュ語、ヘブライ語および東欧諸国語用のもので、AbiWord の CVS 内で "uspell" モジュールとしてホストされています)`
- `Hspell (ヘブライ語)`
- `AppleSpell (Mac OSX)`

# インストール/設定

## 目次

- 要件
- インストール手順
- リソース型

## 要件

このバージョンは、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

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0)

enchant_broker_describe — Enchant プロバイダを列挙する

### 説明

function enchant_broker_describe(EnchantBroker `$broker`): array

Enchant プロバイダを列挙し、その基本情報を通知します。 同じ情報が phpinfo() からでも取得できます。

### パラメータ

`broker`
  enchant_broker_init() によって返される Enchant ブローカー。

### 戻り値

利用可能な Enchant プロバイダの一覧と、その詳細を array として返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `broker` は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource が期待されていました。
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_dict_exists

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_dict_exists — 辞書が存在するかどうかを調べる

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource が期待されていました。

### 例

例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_free

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_free — ブローカーリソースおよびその辞書を開放する

警告

この関数は PHP 8.0.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function enchant_broker_free(EnchantBroker `$broker`): bool

ブローカーをその辞書とともに開放します。 PHP 8.0.0 以降では、この関数を呼び出さず、オブジェクト自体を unset することを推奨します。

### パラメータ

`broker`
  enchant_broker_init() によって返される Enchant ブローカー。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | この関数は、推奨されなくなりました。 オブジェクトを unset する方が好ましいです。
8.0.0 | `broker` は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource が期待されていました。

### 参考

- enchant_broker_init() - 新しいブローカーオブジェクトを作成する

# 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 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function 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 | この関数は、推奨されなくなりました。 オブジェクトを unset する方が好ましいです。
8.0.0 | `dictionary` は、EnchantDictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource が期待されていました。

### 参考

- enchant_broker_request_dict() - タグを使用して新しい辞書を作成する
- enchant_broker_request_pwl_dict() - PWL ファイルを使用して辞書を作成する

# 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 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function 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 | この関数は、推奨されなくなりました。
8.0.0 | `broker` は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource が期待されていました。

### 注意

> 注意: この関数は、拡張モジュールが Enchant v1 を使ってコンパイルされた場合にのみ利用可能です。

### 参考

- enchant_broker_set_dict_path() - 指定されたバックエンドの辞書のパスを設定する

# enchant_broker_get_error

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_get_error — ブローカーの直近のエラーを返す

### 説明

function enchant_broker_get_error(EnchantBroker `$broker`): string|false

このブローカーで発生した直近のエラーを返します。

### パラメータ

`broker`
  enchant_broker_init() によって返される Enchant ブローカー。

### 戻り値

エラーが見つかった場合にメッセージ文字列、それ以外の場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `broker` は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource が期待されていました。

# enchant_broker_init

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_init — 新しいブローカーオブジェクトを作成する

### 説明

function enchant_broker_init(): EnchantBroker|false

### パラメータ

### 戻り値

成功した場合にブローカーリソース、それ以外の場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | 成功時に、この関数は EnchantBroker のインスタンスを返すようになりました。 これより前のバージョンでは、resource が返されていました。

### 参考

- enchant_broker_free() - ブローカーリソースおよびその辞書を開放する

# enchant_broker_list_dicts

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 1.0.1)

enchant_broker_list_dicts — 使用可能な辞書の一覧を返す

### 説明

function enchant_broker_list_dicts(EnchantBroker `$broker`): array

使用可能な辞書の一覧と、その詳細を返します。

### パラメータ

`broker`
  enchant_broker_init() によって返される Enchant ブローカー。

### 戻り値

使用可能な辞書の一覧と、その詳細を array として返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `broker` は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource が期待されていました。
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_request_dict

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_request_dict — タグを使用して新しい辞書を作成する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource が期待されていました。
8.0.0 | 成功時に、この関数は EnchantDictionary のインスタンスを返すようになりました。 これより前のバージョンでは、resource が返されていました。

### 例

例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($broker, $tag);
        var_dump($dict);
    }
    ?>

### 参考

- enchant_dict_describe() - 個々の辞書について説明する
- enchant_broker_dict_exists() - 辞書が存在するかどうかを調べる
- enchant_broker_free_dict() - 辞書リソースを開放する

# 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 ファイルを使用して辞書を作成する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource が期待されていました。
8.0.0 | 成功時に、この関数は EnchantDictionary のインスタンスを返すようになりました。 これより前のバージョンでは、resource が返されていました。

### 参考

- enchant_dict_describe() - 個々の辞書について説明する
- enchant_broker_dict_exists() - 辞書が存在するかどうかを調べる
- enchant_broker_free_dict() - 辞書リソースを開放する

# 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 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function 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 | この関数は、推奨されなくなりました。
8.0.0 | `broker` は、EnchantBroker クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource が期待されていました。

### 注意

> 注意: この関数は、拡張モジュールが Enchant v1 を使ってコンパイルされた場合にのみ利用可能です。

### 参考

- enchant_broker_get_dict_path() - 指定されたバックエンドの辞書のパスを取得する

# enchant_broker_set_ordering

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_broker_set_ordering — その言語で使用する辞書の優先順位を宣言する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource が期待されていました。

# enchant_dict_add

(PHP 8)

enchant_dict_add — 単語リストに単語を追加する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource が期待されていました。

### 例

例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_request_pwl_dict() - PWL ファイルを使用して辞書を作成する
- enchant_broker_request_dict() - タグを使用して新しい辞書を作成する

# 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_session

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_add_to_session — '単語' を、このスペルチェックセッションに追加する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource が期待されていました。

### 参考

- enchant_broker_request_dict() - タグを使用して新しい辞書を作成する

# enchant_dict_check

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_check — 単語のスペルが正しいかどうかを調べる

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource が期待されていました。

# enchant_dict_describe

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_describe — 個々の辞書について説明する

### 説明

function enchant_dict_describe(EnchantDictionary `$dictionary`): array

辞書の詳細を返します。

### パラメータ

`dictionary`
  enchant_broker_request_dict() または enchant_broker_request_pwl_dict() によって返される Enchant 辞書。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `dictionary` は、EnchantDictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource が期待されていました。
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($broker, $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_get_error

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_get_error — 現在のスペリングセッションの直近のエラーを返す

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource が期待されていました。

# enchant_dict_is_added

(PHP 8)

enchant_dict_is_added — 現在のセッションに、単語が存在するかどうかを調べる

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource が期待されていました。

### 参考

- enchant_dict_add_to_session() - '単語' を、このスペルチェックセッションに追加する

# 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_quick_check

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant:0.2.0-1.0.1)

enchant_dict_quick_check — 単語のスペルが正しいかどうかを調べ、修正候補を提供する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource が期待されていました。

### 例

例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_store_replacement

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_store_replacement — 単語の修正候補を追加する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource が期待されていました。

# enchant_dict_suggest

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL enchant >= 0.1.0 )

enchant_dict_suggest — 単語のスペルの修正候補を提示する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource が期待されていました。

### 例

例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 "Suggestions for 'soong':";
            print_r($suggs);
        }
    }
    ?>

### 参考

- enchant_dict_check() - 単語のスペルが正しいかどうかを調べる
- enchant_dict_quick_check() - 単語のスペルが正しいかどうかを調べ、修正候補を提供する

## 目次

- 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 クラス

(PHP 8)

## はじめに

PHP 8.0.0 以降、 `enchant_broker` リソースを置き換える完全不透明クラスです。

## クラス概要

final class EnchantBroker {
}

# EnchantDictionary クラス

(PHP 8)

## はじめに

PHP 8.0.0 以降、 `enchant_dict` リソースを置き換える完全不透明クラスです。

## クラス概要

final class EnchantDictionary {
}

- インストール/設定
  - 要件
  - インストール手順
  - リソース型
- 定義済み定数
- 例
- 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 クラス

# 名前の性別の判別

# はじめに

Gender 拡張モジュールは、Joerg Michael によるプログラム gender.c を PHP に移植したものです。主目的は、ファーストネームから性別を判断することです。 データベースには、現時点で 54か国から 40000 を超えるファーストネームが含まれています。

# インストール/設定

## 目次

- インストール手順

## インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/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 function __construct(string `$dsn` = ?)
public function connect(string `$dsn`): bool
public function country(int `$country`): array|false
public function get(string `$name`, int `$country` = ?): int
public function isNick(string `$name0`, string `$name1`, int `$country` = ?): array
public function 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

(PECL gender >= 0.6.0)

Gender\Gender::connect — 外部の名前ディレクトリに接続する

### 説明

public function Gender\Gender::connect(string `$dsn`): bool

外部の名前ディレクトリに接続します。 今のところ、サポートしているのはストリームだけです。

### パラメータ

`dsn`
  開きたい DSN。

### 戻り値

成功したかどうかを boolean で返します。

# Gender\Gender::__construct

(PECL gender >= 0.6.0)

Gender\Gender::__construct — Gender オブジェクトを作る

### 説明

public function Gender\Gender::__construct(string `$dsn` = ?)

Gender オブジェクトを作ります。オプションで、外部の名前ディレクトリに接続することもできます。 外部データベースを指定しなかったときは、コンパイル時に組み込まれたデータを使います。

### パラメータ

`dsn`
  開きたい DSN。

# Gender\Gender::country

(PECL gender >= 0.8.0)

Gender\Gender::country — 国を表すテキストを取得する

### 説明

public function 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::get

(PECL gender >= 0.6.0)

Gender\Gender::get — 性別を取得する

### 説明

public function Gender\Gender::get(string `$name`, int `$country` = ?): int

指定した名前について、特定の国における性別を取得します。

### パラメータ

`name`
  調べたい名前。
`country`
  Gender クラスの定数で表される国 ID。

### 戻り値

性別を返します。

# Gender\Gender::isNick

(PECL gender >= 0.9.0)

Gender\Gender::isNick — name0 が name1 のエイリアスかどうかを調べる

### 説明

public function Gender\Gender::isNick(string `$name0`, string `$name1`, int `$country` = ?): array

name0 が name1 のエイリアスかどうかを調べます。

### パラメータ

`name0`
  調べる名前。
`name1`
  調べる名前。
`country`
  Gender クラスの定数で指定する国 ID。省略した場合は ANY_COUNTRY を使います。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

# Gender\Gender::similarNames

(PECL gender >= 0.9.0)

Gender\Gender::similarNames — 似た名前を取得する

### 説明

public function Gender\Gender::similarNames(string `$name`, int `$country` = ?): array

名前と国を指定して、似た名前を取得します。

### パラメータ

`name`
  調べる名前。
`country`
  Gender クラスの定数で指定する国 ID。省略した場合は ANY_COUNTRY を使います。

### 戻り値

似ている名前の配列を返します。

## 目次

- 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 クラス
  - Gender\Gender::connect — 外部の名前ディレクトリに接続する
  - Gender\Gender::__construct — Gender オブジェクトを作る
  - Gender\Gender::country — 国を表すテキストを取得する
  - Gender\Gender::get — 性別を取得する
  - Gender\Gender::isNick — name0 が name1 のエイリアスかどうかを調べる
  - Gender\Gender::similarNames — 似た名前を取得する

# Gettext

# はじめに

gettext 関数は、NLS (Native Language Support) API を実装するもので、 PHP アプリケーションを国際化する際に使用することが可能です。 これらの関数の詳細については、システムの gettext ドキュメントを 参照するか、 » http://www.gnu.org/software/gettext/manual/gettext.html のドキュメントをごらんください。

# インストール/設定

## 目次

- 要件
- インストール手順

## 要件

以下の関数を使用するには、» http://www.gnu.org/software/gettext/gettext.html から GNU gettext パッケージをダウンロードし、インストールする必要があります。

## インストール手順

PHP で GNU gettext サポートを有効にするには、オプション --with-gettext[=DIR] を追加する必要が あります。ただし、DIR は gettext をインストールするディレクトリで、 デフォルトは /usr/local です。

# Gettext 関数

# _

(PHP 4, PHP 5, PHP 7, PHP 8)

_ — gettext() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 gettext().

# bind_textdomain_codeset

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

bind_textdomain_codeset — DOMAIN メッセージカタログから返されるメッセージの文字エンコーディングを設定/取得する

### 説明

function bind_textdomain_codeset(string `$domain`, ?string `$codeset` = `null`): string|false

bind_textdomain_codeset() を使用することで、 gettext() やその類似の関数において返される、 `domain` からのメッセージの文字エンコーディングを 設定したり、取得することが可能です。

### パラメータ

`domain`

  ドメイン。

`codeset`

  コードセット。 `null` を指定すると、現在設定されているエンコーディングが返されます。

### 戻り値

成功した場合に文字列を返します。

### エラー / 例外

`domain` が空の string である場合、 ValueError をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `domain` が空の string である場合、 ValueError をスローするようになりました。
8.4.0 | `codeset` パラメータが任意になりました。 これより前のバージョンでは、常に指定しなければなりませんでした。
8.0.3 | `codeset` は、nullable になりました。 これより前のバージョンでは、 現在設定されているエンコーディングは取得できませんでした。

### 注意

> 注意:

> bind_textdomain_codeset() 関数の情報はプロセス単位で管理されます。 スレッドではありません。

# bindtextdomain

(PHP 4, PHP 5, PHP 7, PHP 8)

bindtextdomain — ドメインのパスを取得/設定する

### 説明

function bindtextdomain(string `$domain`, ?string `$directory` = `null`): string|false

bindtextdomain() 関数は、ドメインへのパスを取得/設定します。

### パラメータ

`domain`

  ドメイン。

`directory`

  ディレクトリのパス。 空文字列を指定すると、現在のディレクトリを指定したことになります。 `null` を指定すると、現在設定されているディレクトリが返されます。

### 戻り値

現在設定されているドメインへのフルパスを返します。 失敗した場合に `false` を返します

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `directory` パラメータが任意になりました。 これより前のバージョンでは、常に指定しなければなりませんでした。
8.0.3 | `directory` は、nullable になりました。 これより前のバージョンでは、現在設定されているディレクトリを取得できませんでした。

### 例

例1 bindtextdomain() の例

    <?php

    $domain = 'myapp';
    echo bindtextdomain($domain, '/usr/share/myapp/locale');

    ?>

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

    /usr/share/myapp/locale

### 注意

> 注意:

> bindtextdomain() 関数の情報はプロセス単位で管理されます。 スレッドではありません。

# dcgettext

(PHP 4, PHP 5, PHP 7, PHP 8)

dcgettext — 単一の参照に関するドメインを上書きする

### 説明

function dcgettext(string `$domain`, string `$message`, int `$category`): string

この関数により単一の参照についてカレントのドメインを上書きすることができます。

### パラメータ

`domain`

  ドメイン。

`message`

  メッセージ。

`category`

  カテゴリ。

### 戻り値

成功した場合に文字列を返します。

### 参考

- gettext() - 現在のドメインのメッセージを参照する

# dcngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

dcngettext — dcgettext の複数形版

### 説明

function dcngettext(
string `$domain`,
string `$singular`,
string `$plural`,
int `$count`,
int `$category`
): string

この関数により単一の複数形メッセージの参照について カレントのドメインを上書きすることができます。

### パラメータ

`domain`

  ドメイン。

`singular`

`plural`

`count`

`category`

### 戻り値

成功した場合に文字列を返します。

### 参考

- ngettext() - gettext の複数形版

# dgettext

(PHP 4, PHP 5, PHP 7, PHP 8)

dgettext — 現在のドメインを上書きする

### 説明

function dgettext(string `$domain`, string `$message`): string

dgettext() 関数により、単一のメッセージ参照について 現在のドメインを上書きすることができます。

### パラメータ

`domain`

  ドメイン。

`message`

  メッセージ。

### 戻り値

成功した場合に文字列を返します。

### エラー / 例外

`domain` が空の string である場合、 ValueError をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `domain` が空の string である場合、 ValueError をスローするようになりました。

### 参考

- gettext() - 現在のドメインのメッセージを参照する

# dngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

dngettext — dgettext の複数形版

### 説明

function dngettext(
string `$domain`,
string `$singular`,
string `$plural`,
int `$count`
): string

dngettext() 関数により、単一の複数形メッセージ参照について 現在のドメインを上書きすることができます。

### パラメータ

`domain`

  ドメイン。

`singular`

`plural`

`count`

### 戻り値

成功した場合に文字列を返します。

### エラー / 例外

`domain` が空の string である場合、 ValueError をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `domain` が空の string である場合、 ValueError をスローするようになりました。

### 参考

- ngettext() - gettext の複数形版

# gettext

(PHP 4, PHP 5, PHP 7, PHP 8)

gettext — 現在のドメインのメッセージを参照する

### 説明

function 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() - ロケール情報を設定する

# ngettext

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

ngettext — gettext の複数形版

### 説明

function 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

    ?>

# textdomain

(PHP 4, PHP 5, PHP 7, PHP 8)

textdomain — デフォルトドメインを設定する

### 説明

function textdomain(?string `$domain` = `null`): string

この関数は、gettext() がコールされた際に検索を 行うドメインを設定します。このドメインは、通常はアプリケーション名から 付けられます。

### パラメータ

`domain`

  新しいメッセージドメイン。`null` を指定すると、現在の設定をそのまま 取得し、変更しません。

### 戻り値

成功すると、この関数はドメインを変更した後に現在のメッセージドメインを 返します。

### エラー / 例外

`domain` が空の string である場合、 ValueError をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `domain` が空の string である場合、 ValueError をスローするようになりました。
8.4.0 | `domain` パラメータが任意になりました。 これより前のバージョンでは、常に指定しなければなりませんでした。

### 注意

> 注意:

> textdomain() 関数の情報はプロセス単位で管理されます。 スレッドではありません。

## 目次

- _ — gettext のエイリアス
- bind_textdomain_codeset — DOMAIN メッセージカタログから返されるメッセージの文字エンコーディングを設定/取得する
- bindtextdomain — ドメインのパスを取得/設定する
- dcgettext — 単一の参照に関するドメインを上書きする
- dcngettext — dcgettext の複数形版
- dgettext — 現在のドメインを上書きする
- dngettext — dgettext の複数形版
- gettext — 現在のドメインのメッセージを参照する
- ngettext — gettext の複数形版
- textdomain — デフォルトドメインを設定する

- インストール/設定
  - 要件
  - インストール手順
- Gettext 関数
  - _ — gettext のエイリアス
  - bind_textdomain_codeset — DOMAIN メッセージカタログから返されるメッセージの文字エンコーディングを設定/取得する
  - bindtextdomain — ドメインのパスを取得/設定する
  - dcgettext — 単一の参照に関するドメインを上書きする
  - dcngettext — dcgettext の複数形版
  - dgettext — 現在のドメインを上書きする
  - dngettext — dgettext の複数形版
  - gettext — 現在のドメインのメッセージを参照する
  - ngettext — gettext の複数形版
  - textdomain — デフォルトドメインを設定する

# iconv

# はじめに

このモジュールには、iconv による文字集合の変換機能へのインターフェイスが含まれています。 このモジュールにより、ローカルな文字集合で表された文字列を、Unicode 文字集合のような 他の文字集合で表わされた文字列に変換することができます。 サポートされる文字集合は、使用するシステムの iconv の実装に依存します。 いくつかのシステムでは iconv 関数は意図した通りに動作しない可能性があることに注意してください。 この場合は、» GNU libiconv ライブラリをインストール すると良いでしょう。 このライブラリの出力は、多くの場合、より妥当なものとなります。

この拡張モジュールには、 多言語スクリプトを書く際に有用な種々のユーティリティが附属しています。 この新機能については、以下のセクションを参照ください。

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定

## 要件

使用しているシステムが、最近の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

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv — ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する

### 説明

function 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_get_encoding

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv_get_encoding — iconv 拡張モジュールの内部設定変数を取得する

### 説明

function 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() - 出力バッファハンドラとして文字エンコーディングを変換する

# iconv_mime_decode

(PHP 5, PHP 7, PHP 8)

iconv_mime_decode — `MIME` ヘッダフィールドをデコードする

### 説明

function 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: Prüfung Prüfung" となります。
    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 ビット文字列に変換する

# iconv_mime_decode_headers

(PHP 5, PHP 7, PHP 8)

iconv_mime_decode_headers — 複数の `MIME` ヘッダフィールドを一度にデコードする

### 説明

function 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 ビット文字列に変換する

# iconv_mime_encode

(PHP 5, PHP 7, PHP 8)

iconv_mime_encode — `MIME` ヘッダフィールドを作成する

### 説明

function 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", "Prüfung Prüfung", $preferences);

    $preferences["scheme"] = "B";
    // この結果は "Subject: =?UTF-8?B?UHLDvGZ1bmcgUHLDvGZ1bmc=?=" となります。
    echo iconv_mime_encode("Subject", "Prüfung Prüfung", $preferences);
    ?>

### 参考

- imap_binary() - 8 ビット文字列を base64 文字列に変換する
- mb_encode_mimeheader() - MIMEヘッダの文字列をエンコードする
- imap_8bit() - 8 ビット文字列を quoted-printable 文字列に変換する
- quoted_printable_encode() - 8 ビット文字列を quoted-printable 文字列に変換する

# iconv_set_encoding

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

iconv_set_encoding — 文字エンコーディング変換用の設定を行なう

### 説明

function 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_strlen

(PHP 5, PHP 7, PHP 8)

iconv_strlen — 文字列の文字数を返す

### 説明

function 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_strpos

(PHP 5, PHP 7, PHP 8)

iconv_strpos — 文字列が最初に現れる場所を見つける

### 説明

function 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_strrpos

(PHP 5, PHP 7, PHP 8)

iconv_strrpos — 文字列が最後に現れる場所を見つける

### 説明

function 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_substr

(PHP 5, PHP 7, PHP 8)

iconv_substr — 文字列の一部を切り出す

### 説明

function 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() - 文字列の一部を得る

# ob_iconv_handler

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

ob_iconv_handler — 出力バッファハンドラとして文字エンコーディングを変換する

### 説明

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

## 目次

- 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 — ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する
  - 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 — 出力バッファハンドラとして文字エンコーディングを変換する

# 国際化関数

# はじめに

国際化用拡張モジュール (これ以降では 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

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定

## 要件

この拡張モジュールをビルドするには » 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://unicode-org.github.io/icu/userguide/locale/ で確認できます。

  デフォルト値は空文字列で、これは 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)
  この変換エイリアスは、別の変換実装を指している可能性があります
`U_BAD_VARIABLE_DEFINITION` (int)
  `'$'` が欠けているか、 変数名が重複しています。
`U_BRK_ASSIGN_ERROR` (int)
  RBBI のルール代入文中の、文法エラー
`U_BRK_ERROR_LIMIT` (int)
  Break Iterator の失敗の限界を示す最後の値でなければいけません
`U_BRK_ERROR_START` (int)
  Break Iterator の失敗を示すコードの始点
`U_BRK_HEX_DIGITS_EXPECTED` (int)
  ルール中のエスケープ文字の一部には、16進数が期待されています
`U_BRK_INIT_ERROR` (int)
  初期化に失敗しました。 おそらくICU Data が存在しません。
`U_BRK_INTERNAL_ERROR` (int)
  内部エラー(バグ) が検知されました
`U_BRK_MALFORMED_RULE_TAG` (int)
  ルール中の `{nnn}` タグが不正です
`U_BRK_MISMATCHED_PAREN` (int)
  RBBI ルール中の括弧の対応が一致しません
`U_BRK_NEW_LINE_IN_QUOTED_STRING` (int)
  RBBI ルール中の閉じクォートが欠けています
`U_BRK_RULE_EMPTY_SET` (int)
  ルールに空のUnicodeセットが含まれています
`U_BRK_RULE_SYNTAX` (int)
  RBBI ルール中の文法エラー
`U_BRK_SEMICOLON_EXPECTED` (int)
  RBBI ルールの最後に `';'` がありません
`U_BRK_UNCLOSED_SET` (int)
  閉じ括弧 `']'` が不足している RBBI ルールが含まれる UnicodeSet
`U_BRK_UNDEFINED_VARIABLE` (int)
  RBBI ルール中の 未定義の `$Variable` を使用しています
`U_BRK_UNRECOGNIZED_OPTION` (int)
  RBBI ルール中のオプションが認識されません
`U_BRK_VARIABLE_REDFINITION` (int)
  RBBI ルール変数が再定義されています
`U_BUFFER_OVERFLOW_ERROR` (int)
  結果が与えられたバッファに収まりません
`U_CE_NOT_FOUND_ERROR` (int)
  変数 top を設定する間にだけ使われていますが、 一般に使用できます。
`U_COLLATOR_VERSION_MISMATCH` (int)
  Collator バージョンが、ベースバージョンと互換性がありません
`U_DIFFERENT_UCA_VERSION` (int)
  ucol_open で UCA バージョンと collator image のバージョン不一致が発生したため、 collator はルールから構築されました。以降の関数の実行には影響ありません。
`U_ENUM_OUT_OF_SYNC_ERROR` (int)
  基底となるコレクションと `UEnumeration` が同期していません
`U_ERROR_LIMIT` (int)
  `U_PLUGIN_ERROR_LIMIT` の別名です
`U_ERROR_WARNING_LIMIT` (int)
  これは常に 最後の警告の値であり、 UErrorCode 警告の限界値を示す必要があります (最後の警告のコード +1）。
`U_ERROR_WARNING_START` (int)
  情報の開始(文法的には正しい)
`U_FILE_ACCESS_ERROR` (int)
  リクエストされたファイルが見つかりませんでした
`U_FMT_PARSE_ERROR_LIMIT` (int)
  フォーマットライブラリエラーの終点
`U_FMT_PARSE_ERROR_START` (int)
  フォーマットライブラリエラーの始点
`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)
  引数の値が不正であることを示します
`U_ILLEGAL_CHAR_FOUND` (int)
  文字の変換: 入力シーケンスが不正です
`U_ILLEGAL_CHAR_IN_SEGMENT` (int)
  ICU 2.4 以降は未使用です。
`U_ILLEGAL_CHARACTER` (int)
  特殊文字が許可されたコンテキストの外に置かれています
`U_ILLEGAL_ESCAPE_SEQUENCE` (int)
  ISO-2022 では不正なエスケープシーケンス
`U_ILLEGAL_PAD_POSITION` (int)
  数値のパターン中で、pad記号が間違った位置にあります
`U_INDEX_OUTOFBOUNDS_ERROR` (int)
  範囲外のインデックスにアクセスしようとしています
`U_INTERNAL_PROGRAM_ERROR` (int)
  ライブラリコード中にバグがあります
`U_INTERNAL_TRANSLITERATOR_ERROR` (int)
  transliterator システムの内部エラーです
`U_INVALID_CHAR_FOUND` (int)
  文字変換: マップできない入力シーケンスです。他のAPI: 不正な文字です。
`U_INVALID_FORMAT_ERROR` (int)
  データフォーマットが期待されたものではありません
`U_INVALID_FUNCTION` (int)
  `'&fn()'` ルールが、 不明な transliterator を指定しています
`U_INVALID_ID` (int)
  `'::id'` ルールが、 不明な transliterator を指定しています
`U_INVALID_PROPERTY_PATTERN` (int)
  ICU 2.4 以降では未使用です
`U_INVALID_RBT_SYNTAX` (int)
  RuleBasedTransliterator パーサーに `'::id'` が渡されています
`U_INVALID_STATE_ERROR` (int)
  現状の状態では、ICUはリクエストされた操作を完了できませんでした。
`U_INVALID_TABLE_FILE` (int)
  変換テーブルファイルが見つかりませんでした
`U_INVALID_TABLE_FORMAT` (int)
  変換テーブルファイルが見つかりましたが、壊れています
`U_INVARIANT_CONVERSION_ERROR` (int)
  invariant converter を使う場合は、 `UChar*` 文字列を `char*` に変換できません
`U_MALFORMED_EXPONENTIAL_PATTERN` (int)
  指数パターン中に、グループ化の記号があります
`U_MALFORMED_PRAGMA` (int)
  `'use'` プラグマが不正です
`U_MALFORMED_RULE` (int)
  ルール中の要素が間違って配置されています
`U_MALFORMED_SET` (int)
  `UnicodeSet` パターンが不正です
`U_MALFORMED_SYMBOL_REFERENCE` (int)
  ICU 2.4 以降では未使用です
`U_MALFORMED_UNICODE_ESCAPE` (int)
  Unicode のエスケープパターンが不正です
`U_MALFORMED_VARIABLE_DEFINITION` (int)
  変数定義が不正です
`U_MALFORMED_VARIABLE_REFERENCE` (int)
  変数の参照が不正です
`U_MEMORY_ALLOCATION_ERROR` (int)
  メモリ割り当てエラー
`U_MESSAGE_PARSE_ERROR` (int)
  メッセージのパースに失敗しました(メッセージフォーマット)
`U_MISMATCHED_SEGMENT_DELIMITERS` (int)
  ICU 2.4 以降では未使用です
`U_MISPLACED_ANCHOR_START` (int)
  アンカーの始点が不正な場所にあります
`U_MISPLACED_COMPOUND_FILTER` (int)
  複合フィルタが不正な場所にあります
`U_MISPLACED_CURSOR_OFFSET` (int)
  カーソルのオフセットが、不正な位置に現れています
`U_MISPLACED_QUANTIFIER` (int)
  A quantifier appears after a segment close delimiter.
`U_MISSING_OPERATOR` (int)
  ルールに演算子がありません
`U_MISSING_RESOURCE_ERROR` (int)
  リクエストされたリソースが見つかりませんでした
`U_MISSING_SEGMENT_CLOSE` (int)
  ICU 2.4 以降では未使用です
`U_MULTIPLE_ANTE_CONTEXTS` (int)
  ante context がひとつ以上あります
`U_MULTIPLE_COMPOUND_FILTERS` (int)
  複合フィルタがひとつ以上あります
`U_MULTIPLE_CURSORS` (int)
  カーソルがひとつ以上あります
`U_MULTIPLE_DECIMAL_SEPARATORS` (int)
  数値のパターンに、小数点の区切り文字が複数存在します
`U_MULTIPLE_DECIMAL_SEPERATORS` (int)
  `U_MULTIPLE_DECIMAL_SEPARATORS` のエイリアスです
`U_MULTIPLE_EXPONENTIAL_SYMBOLS` (int)
  数値のパターンに、複数の指数記号があります
`U_MULTIPLE_PAD_SPECIFIERS` (int)
  数値のパターンに、複数のpad記号があります
`U_MULTIPLE_PERCENT_SYMBOLS` (int)
  数値のパターンに、複数のパーセント記号があります
`U_MULTIPLE_PERMILL_SYMBOLS` (int)
  数値のパターンに、複数のパーミル記号があります
`U_MULTIPLE_POST_CONTEXTS` (int)
  post コンテキストがひとつ以上あります
`U_NO_SPACE_AVAILABLE` (int)
  Arabic shaping 向けのバッファ内拡張に空き領域がありません
`U_NO_WRITE_PERMISSION` (int)
  読み取り専用、または定数データを変更しようとしました
`U_PARSE_ERROR` (int)
  Java の `ParseException` と同じです
`U_PARSE_ERROR_LIMIT` (int)
  Transliterator error の終点
`U_PARSE_ERROR_START` (int)
  Transliterator error の始点
`U_PATTERN_SYNTAX_ERROR` (int)
  フォーマットパターン中の文法エラー
`U_PRIMARY_TOO_LONG_ERROR` (int)
  ユーザーが、変数 top を2バイトを超えるプライマリに設定しようとしました
`U_REGEX_BAD_ESCAPE_SEQUENCE` (int)
  パターン中のバックスラッシュエスケープシーケンスが認識できません
`U_REGEX_BAD_INTERVAL` (int)
  `{min,max}` 区間中のエラー
`U_REGEX_ERROR_LIMIT` (int)
  この値は、正規表現エラーコードの限界を示す最後の値でなければなりません
`U_REGEX_ERROR_START` (int)
  正規表現エラーを示すコードの始点
`U_REGEX_INTERNAL_ERROR` (int)
  内部エラー(バグ) が検知されました
`U_REGEX_INVALID_BACK_REF` (int)
  存在しないキャプチャグループに対する後方参照
`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)
  `{min,max}` パターン中で、 max が min より小さいです。
`U_REGEX_MISMATCHED_PAREN` (int)
  正規表現パターン中の括弧のネストが正しくありません
`U_REGEX_NUMBER_TOO_BIG` (int)
  10進数の数が大き過ぎます
`U_REGEX_PROPERTY_SYNTAX` (int)
  不正な Unicode プロパティ
`U_REGEX_RULE_SYNTAX` (int)
  正規表現パターン中の文法エラー
`U_REGEX_SET_CONTAINS_STRING` (int)
  Regexps cannot have `UnicodeSet`s 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)
  これは常に標準的なエラーの最後を示す値でなければいけません
`U_STATE_OLD_WARNING` (int)
  ICU がサービスを作成するのに互換レイヤを使わなければいけません。 パフォーマンス/メモリ使用率 が悪化します。
`U_STATE_TOO_OLD_ERROR` (int)
  未サポートのため、ICU はこの状態からサービスを作成できません。
`U_STRING_NOT_TERMINATED_WARNING` (int)
  出力の `length==destCapacity` になっているため、 出力文字列はNUL終端できません。
`U_STRINGPREP_CHECK_BIDI_ERROR` (int)
  `U_IDNA_CHECK_BIDI_ERROR` のエイリアスです
`U_STRINGPREP_PROHIBITED_ERROR` (int)
  `U_IDNA_PROHIBITED_ERROR` のエイリアスです
`U_STRINGPREP_UNASSIGNED_ERROR` (int)
  `U_IDNA_UNASSIGNED_ERROR` のエイリアスです
`U_TOO_MANY_ALIASES_ERROR` (int)
  リクエストされたリソースのパス中に、エイリアスが多過ぎます。 エイリアスの定義に循環が発生している可能性があります。
`U_TRAILING_BACKSLASH` (int)
  中途半端な行末のバックスラッシュ (訳注: 後にコマンドが続いていないのに、行末がバックスラッシュで終わっている状態)
`U_TRUNCATED_CHAR_FOUND` (int)
  文字変換: 不完全な入力シーケンスです
`U_UNCLOSED_SEGMENT` (int)
  閉じ括弧 `')'` がありません
`U_UNDEFINED_SEGMENT_REFERENCE` (int)
  セグメント参照は、定義済みセグメントに対応していません
`U_UNDEFINED_VARIABLE` (int)
  変数の参照が、定義済みの変数に対応していません
`U_UNEXPECTED_TOKEN` (int)
  フォーマットパターン中の文法エラー
`U_UNMATCHED_BRACES` (int)
  メッセージパターン中のブレースがマッチしません
`U_UNQUOTED_SPECIAL` (int)
  特殊文字がクォートされていないか、エスケープされていません
`U_UNSUPPORTED_ATTRIBUTE` (int)
  ICU 2.4 以降では未使用です
`U_UNSUPPORTED_ERROR` (int)
  現在のコンテキストでは、リクエストされた操作はサポートされていません
`U_UNSUPPORTED_ESCAPE_SEQUENCE` (int)
  ISO-2022 では未サポートのエスケープシーケンスです
`U_UNSUPPORTED_PROPERTY` (int)
  ICU 2.4 以降では未使用です
`U_UNTERMINATED_QUOTE` (int)
  シングルクォートの終端が欠けています
`U_USELESS_COLLATOR_ERROR` (int)
  Collator はオプションでのみ指定できます。 ベースが指定されていません。
`U_USING_DEFAULT_WARNING` (int)
  リソースバンドルの検索結果が、root ロケールから結果を返しました(エラーではありません)
`U_USING_FALLBACK_WARNING` (int)
  リソースバンドルの検索結果が、フォールバック結果を返しました(エラーではありません)
`U_VARIABLE_RANGE_EXHAUSTED` (int)
  指定された変数範囲に対して、生成された代入値が多過ぎます
`U_VARIABLE_RANGE_OVERLAP` (int)
  変数の範囲が、ルール中で使われている文字と重なっています
`U_ZERO_ERROR` (int)
  エラーなし。警告もありません。

# 例

## 目次

- 基本的な使用法

## 基本的な使用法

各モジュールには、 手続き型とオブジェクト指向型の二種類の 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 function __construct(string `$locale`)
public function asort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool
public function compare(string `$string1`, string `$string2`): int|false
public static function create(string `$locale`): ?Collator
public function getAttribute(int `$attribute`): int|false
public function getErrorCode(): int|false
public function getErrorMessage(): string|false
public function getLocale(int `$type`): string|false
public function getSortKey(string `$string`): string|false
public function getStrength(): int
public function setAttribute(int `$attribute`, int `$value`): bool
public function setStrength(int `$strength`): true
public function sort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool
public function sortWithSortKeys(array `&$array`): bool
}

## 定義済み定数

`Collator::FRENCH_COLLATION` int

  文字列の後に続くさまざまなアクセントによる並べ替えを行います。 この属性は、フランス語などの一部のロケールでは自動的に On となります。 通常は、この属性を明示的に設定する必要はありません。 これを On にすると文字列の比較の効率が落ちますが、 ソートキーの長さは影響を受けません。 使用できる値は次のとおりです。

  - `Collator::ON`
  - `Collator::OFF`(デフォルト)
  - `Collator::DEFAULT_VALUE`

  例1 FRENCH_COLLATION のルール

  - F=OFF cote < coté < côte < côté
  - F=ON cote < côte < coté < côté
`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` int

  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` int

  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 = rôle
  - S=1, E=O role = rôle < Role
`Collator::NORMALIZATION_MODE` int

  Normalization 設定は、比較時にテキストを正規化するか否かを指定します。 この設定を off (多くのロケールにおけるデフォルト設定です) にしても、 一般的な使用法ではほぼ正確に利用できます (詳細は UTN #5 を参照ください)。 問題となるのは、アクセント記号が正規の位置以外に登場する場合などです。 この設定を On にすると、 どんなテキストが与えられたとしても可能な限り結果を保証するようにします。 この属性を On にすると、 文字列比較のパフォーマンスに中程度の影響を及ぼします。 影響の程度は、正規化を要する並びの登場頻度に依存します。 ソートキーの長さには、目立った影響は及ぼしません。 入力テキストが NFD あるいは NFKD 形式で正規化されている場合は、 このオプションを有効にする必要はありません。

  使用できる値は次のとおりです。

  - `Collator::OFF`(デフォルト)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::STRENGTH` int

  ICU Collation Service は、多くの比較レベルをサポートしています ("レベル" という名前ですが、"強度" と呼ばれることもあります)。 これらのカテゴリを用いることで、ICU は、 各地域の規約にあわせた適切な文字列の並べ替えを正確に行えるようになります。 また、各段階を選択して採用することで、 テキスト内の文字列検索をさまざまな条件で行うことも可能になります。 詳細な情報は collator_set_strength() を参照ください。

  使用できる値は次のとおりです。

  - `Collator::PRIMARY`
  - `Collator::SECONDARY`
  - `Collator::TERTIARY`(デフォルト)
  - `Collator::QUATERNARY`
  - `Collator::IDENTICAL`
  - `Collator::DEFAULT_VALUE`
`Collator::HIRAGANA_QUATERNARY_MODE` int

  JIS x 4061 との互換性を維持するには、さらなるレベルを追加して ひらがなとカタカナを区別する必要があります。 標準規格との互換性を要する場合は、この属性を On にして強度を Quaternary にしなければなりません。 これは、ソートキーの長さにも文字列比較のパフォーマンスにも影響を及ぼします。

  使用できる値は次のとおりです。

  - `Collator::OFF`(デフォルト)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::NUMERIC_COLLATION` int

  on にすると、数値形式の文字列の各桁を数値として使用した照合キーを生成します。 これにより、'100' のほうが '2' より「後」に並ぶようになります。

  使用できる値は次のとおりです。

  - `Collator::OFF`(デフォルト)
  - `Collator::ON`
  - `Collator::DEFAULT_VALUE`
`Collator::DEFAULT_VALUE` int
`Collator::PRIMARY` int
`Collator::SECONDARY` int
`Collator::TERTIARY` int
`Collator::DEFAULT_STRENGTH` int
`Collator::QUATERNARY` int
`Collator::IDENTICAL` int
`Collator::OFF` int
`Collator::ON` int
`Collator::SHIFTED` int
`Collator::NON_IGNORABLE` int
`Collator::LOWER_FIRST` int
`Collator::UPPER_FIRST` int
`Collator::SORT_REGULAR` int

`Collator::SORT_STRING` int

`Collator::SORT_NUMERIC` int

## 変更履歴

バージョン | 説明
--- | ---
8.4.0 | クラス定数が型付けされました。

# Collator::asort

# collator_asort

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::asort -- collator_asort — インデックスの情報を保持しつつ配列を並べ替える

### 説明

オブジェクト指向型

public function Collator::asort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool

手続き型

function 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 とキーで配列を並べ替える

# Collator::compare

# collator_compare

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::compare -- collator_compare — ふたつの Unicode 文字列を比較する

### 説明

オブジェクト指向型

public function Collator::compare(string `$string1`, string `$string2`): int|false

手続き型

function 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( 'Séan', 'Sean' ) == 0 )
    {
        echo "The same\n";
    }

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

The same

この例は、collator に基本的な文字のみを考慮するように指示します。 Collator->setStrength() のドキュメントは、照合強度の違いについて説明しています。

### 参考

- collator_sort() - 指定した collator で配列を並べ替える

# Collator::__construct

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::__construct — collator を作成する

### 説明

public function 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::create

# collator_create

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::create -- collator_create — collator を作成する

### 説明

オブジェクト指向型

public static function Collator::create(string `$locale`): ?Collator

手続き型

function 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::getAttribute

# collator_get_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::getAttribute -- collator_get_attribute — 照合用の属性の値を取得する

### 説明

オブジェクト指向型

public function Collator::getAttribute(int `$attribute`): int|false

手続き型

function 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::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 function Collator::getErrorCode(): int|false

手続き型

function 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::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 function Collator::getErrorMessage(): string|false

手続き型

function 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::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 function Collator::getLocale(int `$type`): string|false

手続き型

function 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::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 function Collator::getSortKey(string `$string`): string|false

手続き型

function 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

例2 Collator::getSortKey() を usort() と一緒に使う例

    <?php

    $data = [
        [ 'name' => '🇳🇱 Derick Rethans', 'linked_account' => 'https://phpc.social/users/derickr' ],
        [ 'name' => 'Elephpant', 'linked_account' => 'https://phpc.social/phpc' ],
        [ 'name' => '🇫🇷 Marcus Bointon', 'linked_account' => 'https://phpc.social/users/Synchro' ],
    ];

    /* Create the collator */
    $col = new Collator('en');

    /* Sort upper-case letters before lower-case letters */
    $col->setAttribute(Collator::CASE_FIRST, Collator::UPPER_FIRST);

    /* Use a user-defined function with sort, that strips out the emojis */
    usort(
        $data,
        function($a, $b) use ($col) {
            /* Remove the character class 'S' (the Symbols), and remove whitespace
             * (with trim) */
            $aName = trim(preg_replace('/\p{S}+/u', '', $a['name']));
            $bName = trim(preg_replace('/\p{S}+/u', '', $b['name']));

                                    /* Create the sort key */
            $aKey = $col->getSortKey($aName);
            $bKey = $col->getSortKey($bName);

                                    /* Use the sort key to signal which element sorts first */
            return $aKey <=> $bKey;
        }
    );

    var_dump($data);
    ?>

上の例の出力は、 たとえば以下のようになります。

array(3) {
[0] =>
array(2) {
'name' =>
string(25) "🇳🇱 Derick Rethans"
'linked_account' =>
string(33) "https://phpc.social/users/derickr"
}
[1] =>
array(2) {
'name' =>
string(9) "Elephpant"
'linked_account' =>
string(24) "https://phpc.social/phpc"
}
[2] =>
array(2) {
'name' =>
string(25) "🇫🇷 Marcus Bointon"
'linked_account' =>
string(33) "https://phpc.social/users/Synchro"
}
}

### 参考

- collator_sort() - 指定した collator で配列を並べ替える
- collator_sort_with_sort_keys() - 指定した 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 function Collator::getStrength(): int

手続き型

function 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::setAttribute

# collator_set_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::setAttribute -- collator_set_attribute — 照合用の属性を設定する

### 説明

オブジェクト指向型

public function Collator::setAttribute(int `$attribute`, int `$value`): bool

手続き型

function 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');
    collator_set_attribute($coll, Collator::NORMALIZATION_MODE, Collator::ON);
    ?>

### 参考

- Collator の定数
- collator_get_attribute() - 照合用の属性の値を取得する
- collator_set_strength() - 照合強度を設定する

# 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 function Collator::setStrength(int `$strength`): true

手続き型

function collator_set_strength(Collator `$object`, int `$strength`): true

» ICU Collation Service は、多くの比較レベルをサポートしています ("レベル" という名前ですが、"強度" と呼ばれることもあります)。 これらのカテゴリを用いることで、ICU は、 各地域の規約にあわせた適切な文字列の並べ替えを正確に行えるようになります。 また、各段階を選択して採用することで、 テキスト内の文字列検索をさまざまな条件で行うことも可能になります。

1. 第一段階 (Primary Level): 一般に、これは元となる文字自体の違いを表すものとして使用します (たとえば "a" < "b")。これが、いちばん強い違いとなります。 たとえば、辞書などではこれを用いてセクション分けしています。 これは、 `level 1` の強度 (level1 strength) ともいいます。

2. 第二段階 (Secondary Level): 文字のアクセント記号を、第二段階の違いとします (たとえば "as" < "às" < "at")。 言語によっては、その他の文字の違いも第二段階の違いとみなすこともあります。 文字列のどこかで第一段階の違いがある場合、第二段階の違いは無視します。 これは、 `level 2` の強度 (level2 strength) ともいいます。

   > 注意:

   > 注意: 言語によっては (たとえばデンマーク語)、 アクセント記号は元の文字とは別の文字とみなすものもあります。 しかし、たいていの言語では、 アクセントなしの文字とアクセントつきの文字の違いは第二段階とみなします。

3. 第三段階 (Tertiary Level): 大文字と小文字の違いを区別するのが第二段階の違いです (たとえば "ao" < "Ao" < "aò")。 さらに、ある文字とその派生形の違い(たとえば "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` を返します。

### 例

例1 collator_set_strength() の例

    <?php
    $arr  = array( 'aò', '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 => 'aò',
    )
    array (
      0 => 'aò',
      1 => 'Ao',
      2 => 'ao',
    )

### 参考

- Collator の定数
- collator_get_strength() - 現在の照合強度を取得する

# Collator::sort

# collator_sort

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Collator::sort -- collator_sort — 指定した collator で配列を並べ替える

### 説明

オブジェクト指向型

public function Collator::sort(array `&$array`, int `$flags` = `Collator::SORT_REGULAR`): bool

手続き型

function 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', 'às', 'as' );

    var_export( $arr );
    collator_sort( $coll, $arr );
    var_export( $arr );
    ?>

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

    array (
      0 => 'at',
      1 => 'às',
      2 => 'as',
    )array (
      0 => 'as',
      1 => 'às',
      2 => 'at',
    )

### 参考

- Collator の定数
- collator_asort() - インデックスの情報を保持しつつ配列を並べ替える
- collator_sort_with_sort_keys() - 指定した 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 function Collator::sortWithSortKeys(array `&$array`): bool

手続き型

function 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( 'Köpfe', 'Kypper', 'Kopfe' );
    $coll = collator_create( 'sv' );

    collator_sort_with_sort_keys( $coll, $arr );
    var_export( $arr );
    ?>

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

    array (
      0 => 'Kopfe',
      1 => 'Kypper',
      2 => 'Köpfe',
    )

### 参考

- Collator の定数
- collator_sort() - 指定した collator で配列を並べ替える
- collator_asort() - インデックスの情報を保持しつつ配列を並べ替える

## 目次

- 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 クラス

(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 DECIMAL_COMPACT_SHORT;
public const int DECIMAL_COMPACT_LONG;
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_ISO;
public const int CURRENCY_PLURAL;
public const int CURRENCY_ACCOUNTING;
public const int CASH_CURRENCY;
public const int CURRENCY_STANDARD;
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_TOWARD_ZERO;
public const int ROUND_AWAY_FROM_ZERO;
public const int ROUND_HALFEVEN;
public const int ROUND_HALFODD;
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 function __construct(string `$locale`, int `$style`, ?string `$pattern` = `null`)
public static function create(string `$locale`, int `$style`, ?string `$pattern` = `null`): ?NumberFormatter
public function format(int|float `$num`, int `$type` = `NumberFormatter::TYPE_DEFAULT`): string|false
public function formatCurrency(float `$amount`, string `$currency`): string|false
public function getAttribute(int `$attribute`): int|float|false
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false
public function getPattern(): string|false
public function getSymbol(int `$symbol`): string|false
public function getTextAttribute(int `$attribute`): string|false
public function parse(string `$string`, int `$type` = `NumberFormatter::TYPE_DOUBLE`, int `&$offset` = `null`): int|float|false
public function parseCurrency(string `$string`, string `&$currency`, int `&$offset` = `null`): float|false
public function setAttribute(int `$attribute`, int|float `$value`): bool
public function setPattern(string `$pattern`): bool
public function setSymbol(int `$symbol`, string `$value`): bool
public function setTextAttribute(int `$attribute`, string `$value`): bool
}

## 定義済み定数

## フォーマッタのタイプ

これらのスタイルは numfmt_create() で使用するもので、フォーマッタの形式を定義します。

`NumberFormatter::PATTERN_DECIMAL` int
  パターンで定義する十進形式
`NumberFormatter::DECIMAL` int
  十進形式
`NumberFormatter::DECIMAL_COMPACT_SHORT` int
  コンパクト表記（短縮形）を使った十進形式。例: "23K", "45B"。PHP 8.5.0 および ICU 56 以降で利用可能です。
`NumberFormatter::DECIMAL_COMPACT_LONG` int
  コンパクト表記（長い形式）を使った十進形式。例: "23 thousand", "45 billion"。PHP 8.5.0 および ICU 56 以降で利用可能です。
`NumberFormatter::CURRENCY` int
  通貨形式
`NumberFormatter::CURRENCY_ISO` int
  ISO 通貨形式（例: "USD1.00"）。PHP 8.5.0 以降で利用可能です。
`NumberFormatter::CURRENCY_PLURAL` int
  複数形の通貨形式（例: "1.00 US dollar" および "3.00 US dollars"）。PHP 8.5.0 以降で利用可能です。
`NumberFormatter::CASH_CURRENCY` int
  現金使用時の通貨記号。例: "NT$3.23" ではなく "NT$3"。PHP 8.5.0 および ICU 54 以降で利用可能です。
`NumberFormatter::CURRENCY_STANDARD` int
  通貨記号。例: "$1.00"。負の値には非会計方式（例: マイナス記号）を使用します。PHP 8.5.0 および ICU 56 以降で利用可能です。
`NumberFormatter::PERCENT` int
  パーセント形式
`NumberFormatter::SCIENTIFIC` int
  科学形式
`NumberFormatter::SPELLOUT` int
  ルールベースの省略しない形式
`NumberFormatter::ORDINAL` int
  ルールベースの序数形式
`NumberFormatter::DURATION` int
  ルールベースの連続形式
`NumberFormatter::PATTERN_RULEBASED` int
  パターンで定義するルールベースの形式
`NumberFormatter::CURRENCY_ACCOUNTING` int
  会計処理のための通貨フォーマット。例: 負の通貨量の場合、`-$3.00` ではなく、`($3.00)` になります。 PHP 7.4.1 と ICU 53 から利用可能です。
`NumberFormatter::DEFAULT_STYLE` int
  そのロケールのデフォルトの形式
`NumberFormatter::IGNORE` int
  PATTERN_DECIMAL のエイリアス

## 数値フォーマットの指定子

これらの定数は、数値のパースやフォーマットの方法を定義します。 numfmt_format() や numfmt_parse() の引数として使用します。

`NumberFormatter::TYPE_DEFAULT` int
  変数の型に由来する型
`NumberFormatter::TYPE_INT32` int
  32 ビット整数値としてフォーマット/パースする
`NumberFormatter::TYPE_INT64` int
  64 ビット整数値としてフォーマット/パースする
`NumberFormatter::TYPE_DOUBLE` int
  浮動小数点数値としてフォーマット/パースする
`NumberFormatter::TYPE_CURRENCY` int
  通貨値としてフォーマット/パースする。PHP 8.3.0 以降は非推奨

## 数値フォーマットの属性

numfmt_get_attribute() および numfmt_set_attribute() で使用する数値フォーマット属性です。

`NumberFormatter::PARSE_INT_ONLY` int
  整数値のみをパースする
`NumberFormatter::GROUPING_USED` int
  グループ区切り文字を使用する
`NumberFormatter::DECIMAL_ALWAYS_SHOWN` int
  常に小数点を表示する
`NumberFormatter::MAX_INTEGER_DIGITS` int
  整数部の最大桁数
`NumberFormatter::MIN_INTEGER_DIGITS` int
  整数部の最小桁数
`NumberFormatter::INTEGER_DIGITS` int
  整数部の桁数
`NumberFormatter::MAX_FRACTION_DIGITS` int
  小数部の最大桁数
`NumberFormatter::MIN_FRACTION_DIGITS` int
  小数部の最小桁数
`NumberFormatter::FRACTION_DIGITS` int
  小数部の桁数
`NumberFormatter::MULTIPLIER` int
  乗数
`NumberFormatter::GROUPING_SIZE` int
  グループ化のサイズ
`NumberFormatter::ROUNDING_MODE` int
  丸めモード
`NumberFormatter::ROUNDING_INCREMENT` int
  切り上げ
`NumberFormatter::FORMAT_WIDTH` int
  format() の出力のパディング幅
`NumberFormatter::PADDING_POSITION` int
  パディングを行う位置。 使用できる引数の値についてはパディング位置に関する定数を参照ください。
`NumberFormatter::SECONDARY_GROUPING_SIZE` int
  第二段階のグループ化のサイズ
`NumberFormatter::SIGNIFICANT_DIGITS_USED` int
  有効数字を使用する
`NumberFormatter::MIN_SIGNIFICANT_DIGITS` int
  有効数字の最小桁数
`NumberFormatter::MAX_SIGNIFICANT_DIGITS` int
  有効数字の最大桁数
`NumberFormatter::LENIENT_PARSE` int
  ルールベースのフォーマットで使用する Lenient パースモード

## 数値フォーマットのテキスト属性

numfmt_get_text_attribute() および numfmt_set_text_attribute() で使用する数値フォーマットテキスト属性です。

`NumberFormatter::POSITIVE_PREFIX` int
  正の数のプレフィックス
`NumberFormatter::POSITIVE_SUFFIX` int
  正の数のサフィックス
`NumberFormatter::NEGATIVE_PREFIX` int
  負の数のプレフィックス
`NumberFormatter::NEGATIVE_SUFFIX` int
  負の数のサフィックス
`NumberFormatter::PADDING_CHARACTER` int
  余白を埋める際に使用する文字
`NumberFormatter::CURRENCY_CODE` int
  ISO 通貨コード
`NumberFormatter::DEFAULT_RULESET` int
  デフォルトのルールセット。 ルールベースのフォーマッタでのみ有効です。
`NumberFormatter::PUBLIC_RULESETS` int
  パブリックルールセット。 これは、ルールベースのフォーマッタでのみ有効です。 これは読み込み専用の属性です。 パブリックルールセットは文字列として返され、 個々のルールセットは ';' (セミコロン) で区切られています。

## シンボルフォーマットの指定子

numfmt_get_symbol() および numfmt_set_symbol() で使用する数値フォーマット記号です。

`NumberFormatter::DECIMAL_SEPARATOR_SYMBOL` int
  小数点
`NumberFormatter::GROUPING_SEPARATOR_SYMBOL` int
  グループ区切り文字
`NumberFormatter::PATTERN_SEPARATOR_SYMBOL` int
  パターン区切り文字
`NumberFormatter::PERCENT_SYMBOL` int
  パーセント記号
`NumberFormatter::ZERO_DIGIT_SYMBOL` int
  ゼロ
`NumberFormatter::DIGIT_SYMBOL` int
  パターン内で数字を表す文字
`NumberFormatter::MINUS_SIGN_SYMBOL` int
  マイナス記号
`NumberFormatter::PLUS_SIGN_SYMBOL` int
  プラス記号
`NumberFormatter::CURRENCY_SYMBOL` int
  通貨記号
`NumberFormatter::INTL_CURRENCY_SYMBOL` int
  国際通貨記号
`NumberFormatter::MONETARY_SEPARATOR_SYMBOL` int
  金額の区切り文字
`NumberFormatter::EXPONENTIAL_SYMBOL` int
  指数記号
`NumberFormatter::PERMILL_SYMBOL` int
  パーミル記号
`NumberFormatter::PAD_ESCAPE_SYMBOL` int
  パディング文字のエスケープ記号
`NumberFormatter::INFINITY_SYMBOL` int
  無限大記号
`NumberFormatter::NAN_SYMBOL` int
  非数値記号
`NumberFormatter::SIGNIFICANT_DIGIT_SYMBOL` int
  有効数字記号
`NumberFormatter::MONETARY_GROUPING_SEPARATOR_SYMBOL` int
  金額のグループ区切り文字

## 丸めモード

numfmt_get_attribute() および numfmt_set_attribute() で、 `NumberFormatter::ROUNDING_MODE` 属性に使用する丸めモードの値です。

`NumberFormatter::ROUND_AWAY_FROM_ZERO`
  `NumberFormatter::ROUND_UP` のエイリアス
`NumberFormatter::ROUND_CEILING` int
  正の無限大に向けて丸めるモード
`NumberFormatter::ROUND_DOWN` int
  ゼロに向けて丸めるモード
`NumberFormatter::ROUND_FLOOR` int
  負の無限大に向けて丸めるモード
`NumberFormatter::ROUND_HALFDOWN` int
  "一番近いところ" に向けて丸めるモード。 両方から等距離にある場合はゼロに向けて丸めます。
`NumberFormatter::ROUND_HALFEVEN` int
  "一番近いところ" に向けて丸めるモード。 両方から等距離にある場合は偶数になるように丸めます。
`NumberFormatter::ROUND_HALFODD`
  "一番近いところ" に向けて丸めるモード。 両方から等距離にある場合は奇数になるように丸めます。
`NumberFormatter::ROUND_HALFUP` int
  "一番近いところ" に向けて丸めるモード。 両方から等距離にある場合はゼロから離れる方向に丸めます。
`NumberFormatter::ROUND_TOWARD_ZERO`
  `NumberFormatter::ROUND_DOWN` のエイリアス
`NumberFormatter::ROUND_UP` int
  ゼロから離れる方向に丸めるモード

## パディングの指定子

numfmt_get_attribute() および numfmt_set_attribute() で、 `NumberFormatter::PADDING_POSITION` 属性に使用するパディング位置の値です。

`NumberFormatter::PAD_AFTER_PREFIX` int
  プレフィックスの後にパディング文字を入れる
`NumberFormatter::PAD_AFTER_SUFFIX` int
  サフィックスの後にパディング文字を入れる
`NumberFormatter::PAD_BEFORE_PREFIX` int
  プレフィックスの前にパディング文字を入れる
`NumberFormatter::PAD_BEFORE_SUFFIX` int
  サフィックスの前にパディング文字を入れる

## 参考

- » ICU formatting documentation
- » ICU number formatters
- » ICU decimal formatters
- » ICU rule-based number formatters

## 変更履歴

バージョン | 説明
--- | ---
8.5.0 | `NumberFormatter::DECIMAL_COMPACT_SHORT`、`NumberFormatter::DECIMAL_COMPACT_LONG`、 `NumberFormatter::CURRENCY_ISO`、`NumberFormatter::CURRENCY_PLURAL`、 `NumberFormatter::CASH_CURRENCY`、`NumberFormatter::CURRENCY_STANDARD` が追加されました。
8.4.0 | クラス定数が型付けされました。

# 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 function NumberFormatter::create(string `$locale`, int `$style`, ?string `$pattern` = `null`): ?NumberFormatter

手続き型

function numfmt_create(string `$locale`, int `$style`, ?string `$pattern` = `null`): ?NumberFormatter

オブジェクト指向型 (コンストラクタ):

public function 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` を返します。

### エラー / 例外

`locale` が不正な場合、 ValueError をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `locale` が不正な場合、 ValueError をスローするように なりました。
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::format

# numfmt_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::format -- numfmt_format — 数値をフォーマットする

### 説明

オブジェクト指向型

public function NumberFormatter::format(int|float `$num`, int `$type` = `NumberFormatter::TYPE_DEFAULT`): string|false

手続き型

function 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);
    var_dump($data);
    ?>

例2 オブジェクト指向の例

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    $data = $fmt->format(1234567.891234567890000);
    var_dump($data);
    ?>

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

    string(13) "1.234.567,891"

### 注意

> 注意:

> このメソッドで実現可能なフォーマットでは、 ICU ライブラリが持つ機能をすべて使えません。 たとえば、短い通貨記号を使ってフォーマットする場合です。

> ICU ライブラリが持つ機能をすべて使うには、 msgfmt_format_message() を使います。

### 参考

- numfmt_get_error_code() - フォーマッタの直近のエラーコードを取得する
- numfmt_format_currency() - 通貨の値をフォーマットする
- numfmt_parse() - 数値をパースする
- msgfmt_format_message() - 手早くメッセージをフォーマットする

# 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 function NumberFormatter::formatCurrency(float `$amount`, string `$currency`): string|false

手続き型

function 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::getAttribute

# numfmt_get_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getAttribute -- numfmt_get_attribute — 属性を取得する

### 説明

オブジェクト指向型

public function NumberFormatter::getAttribute(int `$attribute`): int|float|false

手続き型

function 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::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 function NumberFormatter::getErrorCode(): int

手続き型

function 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))) {
        echo 'Formatter error';
    }
    ?>

例2 オブジェクト指向の例

    <?php
    $fmt = new NumberFormatter( 'de_DE', NumberFormatter::DECIMAL );
    $fmt->format(1234567.891234567890000);
    if (intl_is_failure($fmt->getErrorCode())) {
        echo 'Formatter error';
    }
    ?>

### 参考

- numfmt_get_error_message() - フォーマッタの直近のエラーメッセージを取得する
- intl_get_error_code() - 直近のエラーコードを取得する
- intl_is_failure() - 指定したエラーコードが失敗を表すかどうかを調べる

# 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 function NumberFormatter::getErrorMessage(): string

手続き型

function 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::getLocale

# numfmt_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getLocale -- numfmt_get_locale — フォーマッタのロケールを取得する

### 説明

オブジェクト指向型

public function NumberFormatter::getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

手続き型

function 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::getPattern

# numfmt_get_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getPattern -- numfmt_get_pattern — フォーマッタのパターンを取得する

### 説明

オブジェクト指向型

public function NumberFormatter::getPattern(): string|false

手続き型

function 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::getSymbol

# numfmt_get_symbol

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::getSymbol -- numfmt_get_symbol — 記号を取得する

### 説明

オブジェクト指向型

public function NumberFormatter::getSymbol(int `$symbol`): string|false

手続き型

function 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::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 function NumberFormatter::getTextAttribute(int `$attribute`): string|false

手続き型

function 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::parse

# numfmt_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::parse -- numfmt_parse — 数値をパースする

### 説明

オブジェクト指向型

public function NumberFormatter::parse(string `$string`, int `$type` = `NumberFormatter::TYPE_DOUBLE`, int `&$offset` = `null`): int|float|false

手続き型

function 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::parseCurrency

# numfmt_parse_currency

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::parseCurrency -- numfmt_parse_currency — 通貨をパースする

### 説明

オブジェクト指向型

public function NumberFormatter::parseCurrency(string `$string`, string `&$currency`, int `&$offset` = `null`): float|false

手続き型

function 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::setAttribute

# numfmt_set_attribute

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setAttribute -- numfmt_set_attribute — 属性を設定する

### 説明

オブジェクト指向型

public function NumberFormatter::setAttribute(int `$attribute`, int|float `$value`): bool

手続き型

function 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

例3 `NumberFormatter::ROUNDING_MODE` を使って値を切り捨てる

デフォルトでは、NumberFormatter は値を丸めます。 `NumberFormatter::ROUNDING_MODE` に `NumberFormatter::ROUND_DOWN` を設定すると、 丸め処理を行わず、指定した小数桁数で値を切り捨てます。

    <?php
    $fmt = new NumberFormatter('en_US', NumberFormatter::DECIMAL);
    $fmt->setAttribute(NumberFormatter::FRACTION_DIGITS, 2);

    echo "Default rounding mode:\n";
    echo $fmt->format(3.789), "\n"; // 3.79 (rounded up)
    echo $fmt->format(3.781), "\n"; // 3.78 (rounded down)

    $fmt->setAttribute(NumberFormatter::ROUNDING_MODE, NumberFormatter::ROUND_DOWN);

    echo "\nWith ROUND_DOWN (truncate):\n";
    echo $fmt->format(3.789), "\n"; // 3.78 (truncated)
    echo $fmt->format(3.781), "\n"; // 3.78 (truncated)
    ?>

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

    Default rounding mode:
    3.79
    3.78

    With ROUND_DOWN (truncate):
    3.78
    3.78

### 参考

- numfmt_get_error_code() - フォーマッタの直近のエラーコードを取得する
- numfmt_get_attribute() - 属性を取得する
- numfmt_set_text_attribute() - テキスト属性を設定する

# 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 function NumberFormatter::setPattern(string `$pattern`): bool

手続き型

function 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::setSymbol

# numfmt_set_symbol

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

NumberFormatter::setSymbol -- numfmt_set_symbol — 記号の値を設定する

### 説明

オブジェクト指向型

public function NumberFormatter::setSymbol(int `$symbol`, string `$value`): bool

手続き型

function 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::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 function NumberFormatter::setTextAttribute(int `$attribute`, string `$value`): bool

手続き型

function 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() - 属性を設定する

## 目次

- 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 クラス

(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 function acceptFromHttp(string `$header`): string|false
public static function canonicalize(string `$locale`): ?string
public static function composeLocale(array `$subtags`): string|false
public static function filterMatches(string `$languageTag`, string `$locale`, bool `$canonicalize` = `false`): ?bool
public static function getAllVariants(string `$locale`): ?array
public static function getDefault(): string
public static function getDisplayLanguage(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getDisplayName(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getDisplayRegion(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getDisplayScript(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getDisplayVariant(string `$locale`, ?string `$displayLocale` = `null`): string|false
public static function getKeywords(string `$locale`): array|false|null
public static function getPrimaryLanguage(string `$locale`): ?string
public static function getRegion(string `$locale`): ?string
public static function getScript(string `$locale`): ?string
public static function isRightToLeft( string `$locale` = "" ): bool
public static function lookup(
array `$languageTag`,
string `$locale`,
bool `$canonicalize` = `false`,
?string `$defaultLocale` = `null`
): ?string
public static function parseLocale(string `$locale`): ?array
public static function setDefault(string `$locale`): true
}

## 定義済み定数

`Locale::DEFAULT_LOCALE` null
  NumberFormatter のようなロケールの影響を受けるさまざまなクラスのメソッドの locale パラメータとして使用します。 この定数は、デフォルトのロケールをメソッドで使用するようにします。

これらの定数は、さまざまなクラスの getLocale メソッドでロケールを選択するために使用します。

`Locale::ACTUAL_LOCALE` int
  これは、データが実際にやってくる元のロケールです。
`Locale::VALID_LOCALE` int
  これは、ICU がサポートする最も明確なロケールです。

## ロケールのサブタグ

これらの定数は、ロケールのパースや合成の方法を定義します。 locale_compose() の引数に渡す配列のキーとして使用し、 また locale_parse() が返す連想配列のキーとしても用いられます。

`Locale::LANG_TAG` string
  言語サブタグ
`Locale::EXTLANG_TAG` string
  拡張言語サブタグ
`Locale::SCRIPT_TAG` string
  文字サブタグ
`Locale::REGION_TAG` string
  地域サブタグ
`Locale::VARIANT_TAG` string
  変化形サブタグ
`Locale::GRANDFATHERED_LANG_TAG` string
  先祖言語 (Grandfathered Language) サブタグ
`Locale::PRIVATE_TAG` string
  プライベートサブタグ

## 参考

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

## 変更履歴

バージョン | 説明
--- | ---
8.4.0 | クラス定数が型付けされました。

# 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 function Locale::acceptFromHttp(string `$header`): string|false

手続き型

function 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::canonicalize

# locale_canonicalize

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::canonicalize -- locale_canonicalize — ロケール文字列を正規化する

### 説明

public static function Locale::canonicalize(string `$locale`): ?string

渡されたロケール文字列を、ICU フォーマットに正規化します。

この関数は有効なロケールを示す、 または返すとは限りません。 単に、ICU の規則に従って正規化された入力のバージョンに過ぎません。

この関数の振る舞いは、 PHP が使っている ICU のバージョン (`INTL_ICU_VERSION`) に依存します。

### パラメータ

`locale`
  オリジナルのロケール文字列

### 戻り値

正規化されたロケール文字列を返します。

`locale` の長さが `INTL_MAX_LOCALE_LEN` を超えた場合、`null` を返します。

### 例

例1 locale_canonicalize() の例

    echo Locale::canonicalize('en-US.utf8') . "\n";
    echo Locale::canonicalize('totally-not-valid') . "\n";

上の例の出力は、 たとえば以下のようになります。

    en_US
    totally_NOT_VALID

# 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 function Locale::composeLocale(array `$subtags`): string|false

手続き型

function 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::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 function Locale::filterMatches(string `$languageTag`, string `$locale`, bool `$canonicalize` = `false`): ?bool

手続き型

function 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::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 function Locale::getAllVariants(string `$locale`): ?array

手続き型

function 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() - 入力ロケールの地域を取得する

# 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 function Locale::getDefault(): string

手続き型

function 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::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 function Locale::getDisplayLanguage(string `$locale`, ?string `$displayLocale` = `null`): string|false

手続き型

function 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::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 function Locale::getDisplayName(string `$locale`, ?string `$displayLocale` = `null`): string|false

手続き型

function locale_get_display_name(string `$locale`, ?string `$displayLocale` = `null`): string|false

入力ロケールの表示名を、適切に地域化して返します。 `locale` が `null` の場合はデフォルトのロケールを使用します。

### 説明

オブジェクト指向型

public static function Locale::getDisplayName(string `$locale`, string `$in_locale` = ?): string

手続き型

function 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::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 function Locale::getDisplayRegion(string `$locale`, ?string `$displayLocale` = `null`): string|false

手続き型

function 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::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 function Locale::getDisplayScript(string `$locale`, ?string `$displayLocale` = `null`): string|false

手続き型

function 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::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 function Locale::getDisplayVariant(string `$locale`, ?string `$displayLocale` = `null`): string|false

手続き型

function 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::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 function Locale::getKeywords(string `$locale`): array|false|null

手続き型

function 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::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 function Locale::getPrimaryLanguage(string `$locale`): ?string

手続き型

function 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::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 function Locale::getRegion(string `$locale`): ?string

手続き型

function 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::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 function Locale::getScript(string `$locale`): ?string

手続き型

function 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::isRightToLeft

(No version information available, might only be in Git)

Locale::isRightToLeft — ロケールが右から左に書く文字体系を使うかどうかを調べる

### 説明

public static function Locale::isRightToLeft( string `$locale` = "" ): bool

ロケールが右から左に書く文字体系を使うかどうかを調べます。

このメソッドは ICU ライブラリに依存しており、 ロケールに関連付けられた主要な文字体系を評価します。

空文字列が指定された場合、デフォルトのロケールが使用されます。

### パラメータ

`locale`
  ロケール識別子。空の場合はデフォルトのロケールが使用されます。

### 戻り値

ロケールが右から左に書く文字体系を使う場合に `true`、 そうでない場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | Locale::isRightToLeft() が追加されました。

### 例

例1 ロケールのテキスト方向を調べる

    <?php

    var_dump(Locale::isRightToLeft('en-US'));
    var_dump(Locale::isRightToLeft('ar'));

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

    bool(false)
    bool(true)

# Locale::lookup

# locale_lookup

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Locale::lookup -- locale_lookup — その言語にマッチする言語タグの一覧を検索する

### 説明

オブジェクト指向型

public static function Locale::lookup(
array `$languageTag`,
string `$locale`,
bool `$canonicalize` = `false`,
?string `$defaultLocale` = `null`
): ?string

手続き型

function 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() - 言語タグフィルタがロケールにマッチするかどうかを調べる

# 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 function Locale::parseLocale(string `$locale`): ?array

手続き型

function 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::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 function Locale::setDefault(string `$locale`): true

手続き型

function locale_set_default(string `$locale`): true

デフォルトの実行時ロケールを `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' からデフォルトのロケールを取得する

## 目次

- 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::isRightToLeft — ロケールが右から左に書く文字体系を使うかどうかを調べる
- Locale::lookup — その言語にマッチする言語タグの一覧を検索する
- Locale::parseLocale — ロケール ID のサブタグ要素を連想配列で返す
- Locale::setDefault — デフォルトの実行時ロケールを設定する

# 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 function getRawDecomposition(string `$string`, int `$form` = `Normalizer::FORM_C`): ?string
public static function isNormalized(string `$string`, int `$form` = `Normalizer::FORM_C`): bool
public static function normalize(string `$string`, int `$form` = `Normalizer::FORM_C`): string|false
}

## 定義済み定数

以下の定数は、使用する正規化方式を定義するものです。

`Normalizer::FORM_C` int
  正規化形式C(NFC) - 正準等価性により分解し正準等価性によって合成
`Normalizer::FORM_D` int
  正規化形式D (NFD) - 正準等価性により分解
`Normalizer::NFD` int

`Normalizer::FORM_KC` int
  正規化形式KC(NFKC) - 互換等価性により分解し正準等価性によって合成
`Normalizer::NFKC` int

`Normalizer::FORM_KC_CF` int

`Normalizer::FORM_KD` int
  正規化形式KD(NFKD) - 互換等価性により分解
`Normalizer::NFKD` int

`Normalizer::NFC` int

`Normalizer::NFKC_CF` int

## 参考

- » Unicode Normalization
- » Unicode Normalization FAQ
- » ICU User Guide - Normalization
- » ICU API Reference - Normalization

## 変更履歴

バージョン | 説明
--- | ---
8.4.0 | クラス定数が型付けされました。
8.0.0 | `Normalizer::NONE` が削除されました。

# Normalizer::getRawDecomposition

# normalizer_get_raw_decomposition

(PHP 7 >= 7.3, PHP 8)

Normalizer::getRawDecomposition -- normalizer_get_raw_decomposition — UTF-8 エンコードされているコードポイントから、Decomposition_Mapping プロパティの値を取得する

### 説明

オブジェクト指向型

public static function Normalizer::getRawDecomposition(string `$string`, int `$form` = `Normalizer::FORM_C`): ?string

手続き型

function 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::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 function Normalizer::isNormalized(string `$string`, int `$form` = `Normalizer::FORM_C`): bool

手続き型

function 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::normalize

# normalizer_normalize

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

Normalizer::normalize -- normalizer_normalize — 渡された入力を正規化し、正規化後の文字列を返す

### 説明

オブジェクト指向型

public static function Normalizer::normalize(string `$string`, int `$form` = `Normalizer::FORM_C`): string|false

手続き型

function 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() - 渡された文字列が、指定した正規化を適用済みかどうかを調べる

## 目次

- Normalizer::getRawDecomposition — UTF-8 エンコードされているコードポイントから、Decomposition_Mapping プロパティの値を取得する
- Normalizer::isNormalized — 渡された文字列が、指定した正規化を適用済みかどうかを調べる
- Normalizer::normalize — 渡された入力を正規化し、正規化後の文字列を返す

# 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 function __construct(string `$locale`, string `$pattern`)
public static function create(string `$locale`, string `$pattern`): ?MessageFormatter
public function format(array `$values`): string|false
public static function formatMessage(string `$locale`, string `$pattern`, array `$values`): string|false
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(): string
public function getPattern(): string|false
public function parse(string `$string`): array|false
public static function parseMessage(string `$locale`, string `$pattern`, string `$message`): array|false
public function setPattern(string `$pattern`): bool
}

## 参考

- » ICU formatting documentation
- » ICU message formatting description
- » ICU message formatters
- » ICU choice formatters

# 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 function MessageFormatter::create(string `$locale`, string `$pattern`): ?MessageFormatter

オブジェクト指向型 (コンストラクタ):

public function MessageFormatter::__construct(string `$locale`, string `$pattern`)

手続き型

function 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} Bäumen 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} Bäumen 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 Bäumen sind 37,073 Affen pro Baum

### 参考

- msgfmt_format() - メッセージをフォーマットする
- msgfmt_parse() - パターンを使用して入力文字列をパースする
- msgfmt_get_error_code() - 直近の操作のエラーコードを取得する
- msgfmt_get_error_message() - 直近の操作のエラーテキストを取得する

# MessageFormatter::format

# msgfmt_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::format -- msgfmt_format — メッセージをフォーマットする

### 説明

オブジェクト指向型

public function MessageFormatter::format(array `$values`): string|false

手続き型

function 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} Bäumen 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} Bäumen 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 Bäumen sind 37,073 Affen pro Baum

### 参考

- msgfmt_create() - 新しいメッセージフォーマッタを作成する
- msgfmt_parse() - パターンを使用して入力文字列をパースする
- msgfmt_format_message() - 手早くメッセージをフォーマットする
- msgfmt_get_error_code() - 直近の操作のエラーコードを取得する
- msgfmt_get_error_message() - 直近の操作のエラーテキストを取得する

# 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 function MessageFormatter::formatMessage(string `$locale`, string `$pattern`, array `$values`): string|false

手続き型

function 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} Bäumen 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} Bäumen 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 Bäumen 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::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 function MessageFormatter::getErrorCode(): int

手続き型

function msgfmt_get_error_code(MessageFormatter `$formatter`): int

直近の操作のエラーコードを取得します。

### パラメータ

`formatter`

  メッセージのフォーマッタ。

### 参考

- msgfmt_get_error_message() - 直近の操作のエラーテキストを取得する
- intl_get_error_code() - 直近のエラーコードを取得する
- intl_is_failure() - 指定したエラーコードが失敗を表すかどうかを調べる

# 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 function MessageFormatter::getErrorMessage(): string

手続き型

function 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::getLocale

# msgfmt_get_locale

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getLocale -- msgfmt_get_locale — フォーマッタを作成した際のロケールを取得する

### 説明

オブジェクト指向型

public function MessageFormatter::getLocale(): string

手続き型

function 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::getPattern

# msgfmt_get_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::getPattern -- msgfmt_get_pattern — フォーマッタが使用するパターンを取得する

### 説明

オブジェクト指向型

public function MessageFormatter::getPattern(): string|false

手続き型

function 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::parse

# msgfmt_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::parse -- msgfmt_parse — パターンを使用して入力文字列をパースする

### 説明

オブジェクト指向型

public function MessageFormatter::parse(string `$string`): array|false

手続き型

function 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} Bäumen sind {2,number} Affen pro Baum");
    $res = msgfmt_parse($fmt, "4.560 Affen auf 123 Bäumen 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} Bäumen sind {2,number} Affen pro Baum");
    $res = $fmt->parse("4.560 Affen auf 123 Bäumen 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::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 function MessageFormatter::parseMessage(string `$locale`, string `$pattern`, string `$message`): array|false

手続き型

function 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} Bäumen sind {2,number} Affen pro Baum",
                                "4.560 Affen auf 123 Bäumen 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} Bäumen sind {2,number} Affen pro Baum",
                                "4.560 Affen auf 123 Bäumen 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::setPattern

# msgfmt_set_pattern

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

MessageFormatter::setPattern -- msgfmt_set_pattern — フォーマッタが使用するパターンを設定する

### 説明

オブジェクト指向型

public function MessageFormatter::setPattern(string `$pattern`): bool

手続き型

function 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() - フォーマッタが使用するパターンを取得する

## 目次

- MessageFormatter::create — 新しいメッセージフォーマッタを作成する
- MessageFormatter::format — メッセージをフォーマットする
- MessageFormatter::formatMessage — 手早くメッセージをフォーマットする
- MessageFormatter::getErrorCode — 直近の操作のエラーコードを取得する
- MessageFormatter::getErrorMessage — 直近の操作のエラーテキストを取得する
- MessageFormatter::getLocale — フォーマッタを作成した際のロケールを取得する
- MessageFormatter::getPattern — フォーマッタが使用するパターンを取得する
- MessageFormatter::parse — パターンを使用して入力文字列をパースする
- MessageFormatter::parseMessage — 手早く入力文字列をパースする
- MessageFormatter::setPattern — フォーマッタが使用するパターンを設定する

# 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 function __construct()
public function add(int `$field`, int `$value`): bool
public function after(IntlCalendar `$other`): bool
public function before(IntlCalendar `$other`): bool
public function clear(?int `$field` = `null`): true
public static function createInstance(IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`, ?string `$locale` = `null`): ?IntlCalendar
public function equals(IntlCalendar `$other`): bool
public function fieldDifference(float `$timestamp`, int `$field`): int|false
public static function fromDateTime(DateTime|string `$datetime`, ?string `$locale` = `null`): ?IntlCalendar
public function get(int `$field`): int|false
public function getActualMaximum(int `$field`): int|false
public function getActualMinimum(int `$field`): int|false
public static function getAvailableLocales(): array
public function getDayOfWeekType(int `$dayOfWeek`): int|false
public function getErrorCode(): int|false
public function getErrorMessage(): string|false
public function getFirstDayOfWeek(): int|false
public function getGreatestMinimum(int `$field`): int|false
public static function getKeywordValuesForLocale(string `$keyword`, string `$locale`, bool `$onlyCommon`): IntlIterator|false
public function getLeastMaximum(int `$field`): int|false
public function getLocale(int `$type`): string|false
public function getMaximum(int `$field`): int|false
public function getMinimalDaysInFirstWeek(): int|false
public function getMinimum(int `$field`): int|false
public static function getNow(): float
public function getRepeatedWallTimeOption(): int
public function getSkippedWallTimeOption(): int
public function getTime(): float|false
public function getTimeZone(): IntlTimeZone|false
public function getType(): string
public function getWeekendTransition(int `$dayOfWeek`): int|false
public function inDaylightTime(): bool
public function isEquivalentTo(IntlCalendar `$other`): bool
public function isLenient(): bool
public function isSet(int `$field`): bool
public function isWeekend(?float `$timestamp` = `null`): bool
public function roll(int `$field`, int|bool `$value`): bool
public function set(int `$field`, int `$value`): true
public function set(
int `$year`,
int `$month`,
int `$dayOfMonth` = NULL,
int `$hour` = NULL,
int `$minute` = NULL,
int `$second` = NULL
): true
public function setDate(int `$year`, int `$month`, int `$dayOfMonth`): void
public function setDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): void
public function setFirstDayOfWeek(int `$dayOfWeek`): true
public function setLenient(bool `$lenient`): true
public function setMinimalDaysInFirstWeek(int `$days`): true
public function setRepeatedWallTimeOption(int `$option`): true
public function setSkippedWallTimeOption(int `$option`): true
public function setTime(float `$timestamp`): bool
public function setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool
public function toDateTime(): DateTime|false
}

## 定義済み定数

`IntlCalendar::FIELD_ERA` int

  カレンダーのフィールドで、時代を表す数値です。たとえば、グレゴリオ暦やユリウス暦の場合は `1` が紀元後そして `0` が紀元前を表します。 また、和暦の場合は `235` が平成を表します。 すべてのカレンダーが複数の時代を持つわけではありません。

`IntlCalendar::FIELD_YEAR` int

  カレンダーの、年を表すフィールド。時代が違えば同じ数字になることもあります。 そのカレンダー型が複数の時代を持っている場合は、このフィールドの最小値は通常は `1` になります。

`IntlCalendar::FIELD_MONTH` int

  カレンダーの、月を表すフィールド。月番号はゼロからはじまるので、1月が `0`、2月が `1`、…そして12月が `11` となります。13番目の月あるいはうるう月があるカレンダーの場合は、`12` で表します。

`IntlCalendar::FIELD_WEEK_OF_YEAR` int

  カレンダーの、年内の週番号を表すフィールド。 これは、何曜日を週の開始日とみなすか、そして週の最小日数は何日かによって決まります。

`IntlCalendar::FIELD_WEEK_OF_MONTH` int

  カレンダーの、月内の週番号を表すフィールド。 これは、何曜日を週の開始日とみなすか、そして週の最小日数は何日かによって決まります。

`IntlCalendar::FIELD_DATE` int

  カレンダーの、月内の日数を表すフィールド。 `IntlCalendar::FIELD_DAY_OF_MONTH` と同じで、こちらのほうがよりわかりやすい名前です。

`IntlCalendar::FIELD_DAY_OF_YEAR` int

  カレンダーの、年内の日数を表すフィールド。 グレゴリオ暦の場合は、`1` から始まって `365` あるいは `366` で終わります。

`IntlCalendar::FIELD_DAY_OF_WEEK` int

  カレンダーの、曜日を表すフィールド。 最初の値は `1` (日曜日。`IntlCalendar::DOW_SUNDAY` とそれに続く定数を参照ください) で、有効な最後の値は 7 (土曜日) です。

`IntlCalendar::FIELD_DAY_OF_WEEK_IN_MONTH` int

  曜日 (日曜日、月曜日、…) を指定されたときに、このフィールドには当月内でその曜日が何番目に登場するのかを代入します。 つまり、このフィールドの値が `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` int

  カレンダーの、午前 (`0`) か午後 (`1`) かを表すフィールド。 深夜 0 時は午前、正午は午後となります。

`IntlCalendar::FIELD_HOUR` int

  カレンダーの、時間を表すフィールド。午前か午後かは含みません。 有効な値は `0` から `11` までです。

`IntlCalendar::FIELD_HOUR_OF_DAY` int

  カレンダーの、24 時間制の時間を表すフィールド。 有効な値は `0` から `23` までです。

`IntlCalendar::FIELD_MINUTE` int

  カレンダーの、分を表すフィールド。

`IntlCalendar::FIELD_SECOND` int

  カレンダーの、秒を表すフィールド。

`IntlCalendar::FIELD_MILLISECOND` int

  カレンダーの、ミリ秒を表すフィールド。

`IntlCalendar::FIELD_ZONE_OFFSET` int

  カレンダーの、タイムゾーンのオフセットをミリ秒で表すフィールド。 夏時間によるオフセットは含みません。

`IntlCalendar::FIELD_DST_OFFSET` int

  カレンダーの、夏時間によるオフセットをミリ秒で表すフィールド。 夏時間を採用しているタイムゾーンの場合に使います。

`IntlCalendar::FIELD_YEAR_WOY` int

  カレンダーの、week of year 用の年を表すフィールド。

`IntlCalendar::FIELD_DOW_LOCAL` int

  カレンダーの、ローカライズした曜日を表すフィールド。 `1` から `7` までの値となり、 `1` は IntlCalendar::getFirstDayOfWeek() が返す値にマッチする曜日に使います。

`IntlCalendar::FIELD_EXTENDED_YEAR` int

  カレンダーの、年番号を表すフィールド。この番号は、時代をまたがって続きます。 グレゴリオ暦の場合、紀元後の年についてはこの値は `IntlCalendar::FIELD_YEAR` に一致します。 紀元前 `y` 年の場合は `-y + 1` となります。

`IntlCalendar::FIELD_JULIAN_DAY` int

  カレンダーの、ユリウス日を表すフィールド。 一般的な慣習とは違って、このユリウス日は現地時間の深夜 0 時に加算されます。 UTC の正午ではありません。 これで、日付を一意に特定します。

`IntlCalendar::FIELD_MILLISECONDS_IN_DAY` int

  カレンダーの、 `IntlCalendar::FIELD_HOUR_OF_DAY` や `IntlCalendar::FIELD_MINUTE`、 `IntlCalendar::FIELD_SECOND`、そして `IntlCalendar::FIELD_MILLISECOND` の情報をまとめたフィールド。 `0` から `24 * 3600 * 1000 - 1` までの値となります。この値は、その日の中での経過ミリ秒数ではありません。 というのも、夏時間への移行を挟む場合はこの値は連続した値にならないからです。

`IntlCalendar::FIELD_IS_LEAP_MONTH` int

  カレンダーのフィールドで、値が `1` のときはうるう月、 `0` の場合はそうでないことを表します。

`IntlCalendar::FIELD_FIELD_COUNT` int

  フィールドの総数。

`IntlCalendar::FIELD_DAY_OF_MONTH` int

  `IntlCalendar::FIELD_DATE` のエイリアス。

`IntlCalendar::DOW_SUNDAY` int

  日曜日。

`IntlCalendar::DOW_MONDAY` int

  月曜日。

`IntlCalendar::DOW_TUESDAY` int

  火曜日。

`IntlCalendar::DOW_WEDNESDAY` int

  水曜日。

`IntlCalendar::DOW_THURSDAY` int

  木曜日。

`IntlCalendar::DOW_FRIDAY` int

  金曜日。

`IntlCalendar::DOW_SATURDAY` int

  土曜日。

`IntlCalendar::DOW_TYPE_WEEKDAY` int

  平日であることを示す IntlCalendar::getDayOfWeekType() の出力。

`IntlCalendar::DOW_TYPE_WEEKEND` int

  週末であることを示す IntlCalendar::getDayOfWeekType() の出力。

`IntlCalendar::DOW_TYPE_WEEKEND_OFFSET` int

  指定した曜日から週末が始まることを示す IntlCalendar::getDayOfWeekType() の出力。

`IntlCalendar::DOW_TYPE_WEEKEND_CEASE` int

  指定した曜日で週末が終わることを示す IntlCalendar::getDayOfWeekType() の出力。

`IntlCalendar::WALLTIME_FIRST` int

  スキップした範囲内の実測時間が一時間前の実測時間と同じ瞬間を指すことを示す IntlCalendar::getSkippedWallTimeOption() の出力。 また、繰り返した範囲内の実測時間がその最初のほうを指すことを示す IntlCalendar::getRepeatedWallTimeOption() の出力。

`IntlCalendar::WALLTIME_LAST` int

  スキップした範囲内の実測時間が一時間後の実測時間と同じ瞬間を指すことを示す IntlCalendar::getSkippedWallTimeOption() の出力。 また、繰り返した範囲内の実測時間がその二番目のほうを指すことを示す IntlCalendar::getRepeatedWallTimeOption() の出力。

`IntlCalendar::WALLTIME_NEXT_VALID` int

  スキップした範囲内の実測時間が夏時間への移行 (開始) を指すことを示す IntlCalendar::getSkippedWallTimeOption() の出力。

## 変更履歴

バージョン | 説明
--- | ---
8.4.0 | クラス定数が型付けされました。

# IntlCalendar::add

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::add — フィールドに (符号付きの) 一定量の時間を追加する

### 説明

オブジェクト指向型

public function IntlCalendar::add(int `$field`, int `$value`): bool

手続き型

function 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 févr. 2012 00:00:00
    1 mars 2012 00:00:00

# IntlCalendar::after

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::after — このオブジェクトの時刻が、指定されたオブジェクトより未来かを判定する

### 説明

オブジェクト指向型

public function IntlCalendar::after(IntlCalendar `$other`): bool

手続き型

function 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::before

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::before — このオブジェクトの時刻が、指定されたオブジェクトより過去かを判定する

### 説明

オブジェクト指向型

public function IntlCalendar::before(IntlCalendar `$other`): bool

手続き型

function intlcal_before(IntlCalendar `$calendar`, IntlCalendar `$other`): bool

このオブジェクトの時刻が、 指定されたオブジェクトの時刻よりより過去かを判定して返します。

### パラメータ

`calendar`
  IntlCalendar クラスのインスタンス。
`other`

  このカレンダーオブジェクトの時刻が、 最初のオブジェクトの時刻と比較されます。

### 戻り値

このオブジェクトの現在時刻が、 `calendar` の時刻より前の場合に `true` を返します。 そうでない場合、`false` を返します。

失敗時に `false` を返します。エラーを検知するには、intl_get_error_code() を使うか、 Intl拡張モジュールが 例外 をスローするように設定して下さい。

# IntlCalendar::clear

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::clear — 単一または全てのフィールドをクリアする

### 説明

オブジェクト指向型

public function IntlCalendar::clear(?int `$field` = `null`): true

手続き型

function 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

# IntlCalendar::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::__construct — インスタンス化を禁止するための private なコンストラクタ

### 説明

private function IntlCalendar::__construct()

new 演算子によるインスタンス化を>拒否するために用意された、 private なコンストラクタです。

IntlCalendar::createInstance() をコールして下さい。

### パラメータ

この関数にはパラメータはありません。

# IntlCalendar::createInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::createInstance — 新しい IntlCalendar を作成する

### 説明

オブジェクト指向型

public static function IntlCalendar::createInstance(IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`, ?string `$locale` = `null`): ?IntlCalendar

手続き型

function 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::equals

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::equals — ふたつの IntlCalendar オブジェクトの時刻を比較する

### 説明

オブジェクト指向型

public function IntlCalendar::equals(IntlCalendar `$other`): bool

手続き型

function 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::fieldDifference

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::fieldDifference — 指定された時刻と、このオブジェクトの時刻の差を計算する

### 説明

オブジェクト指向型

public function IntlCalendar::fieldDifference(float `$timestamp`, int `$field`): int|false

手続き型

function intlcal_field_difference(IntlCalendar `$calendar`, float `$timestamp`, int `$field`): int|false

`field` に設定された量も考慮して、 指定された時刻と、このオブジェクトに設定された時刻の差を返します。

このメソッドは連続して呼び出すものです。 最初は、関心のある重要なフィールドからはじめ、 もっとも関心が薄いフィールドへと続きます。 最終的な副作用として、 このカレンダーの指定されたフィールドの値が、 返される量だけ進みます。

### パラメータ

`calendar`
  IntlCalendar クラスのインスタンス。
`timestamp`

  `field` が表す、比較する時刻の量。 結果を正の値にするには、 この引数で指定する値を、 このメソッドを呼び出すオブジェクトの時刻よりも、 未来に設定しなければいけません。

`field`

  比較される量を表すフィールド。

  IntlCalendar の日付/時刻 フィールド定数 のいずれか。 `0` から `IntlCalendar::FIELD_COUNT` までの間の整数値です。

### 戻り値

指定されたフィールドに関連付けられた単位で、 (符号付きで)時刻の差を返します。 失敗した場合に `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 févr. 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

# IntlCalendar::fromDateTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a2)

IntlCalendar::fromDateTime — DateTime オブジェクトまたは文字列から、IntlCalendar を作成する

### 説明

オブジェクト指向型

public static function IntlCalendar::fromDateTime(DateTime|string `$datetime`, ?string `$locale` = `null`): ?IntlCalendar

手続き型

function 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', 'de_DE');

    //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::get

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::get — フィールドの値を取得する

### 説明

オブジェクト指向型

public function IntlCalendar::get(int `$field`): int|false

手続き型

function 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::getActualMaximum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getActualMaximum — オブジェクトの現在時刻を考慮して、フィールドの最大値を取得する

### 説明

オブジェクト指向型

public function IntlCalendar::getActualMaximum(int `$field`): int|false

手続き型

function 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::getActualMinimum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getActualMinimum — オブジェクトの現在時刻を考慮して、フィールドの最小値を取得する

### 説明

オブジェクト指向型

public function IntlCalendar::getActualMinimum(int `$field`): int|false

手続き型

function 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::getAvailableLocales

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getAvailableLocales — データが存在するロケールの配列を取得する

### 説明

オブジェクト指向型

public static function IntlCalendar::getAvailableLocales(): array

手続き型

function 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::getDayOfWeekType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getDayOfWeekType — 指定された日が平日か、週末か、ふたつの週の間の移行日かを返す

### 説明

オブジェクト指向型

public function IntlCalendar::getDayOfWeekType(int `$dayOfWeek`): int|false

手続き型

function 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::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 function IntlCalendar::getErrorCode(): int|false

手続き型:

function 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::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 function IntlCalendar::getErrorMessage(): string|false

手続き型:

function 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::getFirstDayOfWeek

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getFirstDayOfWeek — カレンダーのロケールに基づいて、週の始めの日を返す

### 説明

オブジェクト指向型

public function IntlCalendar::getFirstDayOfWeek(): int|false

手続き型

function 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::getGreatestMinimum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getGreatestMinimum — 指定されたフィールドの、ローカルな最小値のうち、最大の値を返す

### 説明

オブジェクト指向型

public function IntlCalendar::getGreatestMinimum(int `$field`): int|false

手続き型

function 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::getKeywordValuesForLocale

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getKeywordValuesForLocale — ロケールのキーワードの値の集合を返す

### 説明

オブジェクト指向型

public static function IntlCalendar::getKeywordValuesForLocale(string `$keyword`, string `$locale`, bool `$onlyCommon`): IntlIterator|false

手続き型

function 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::getKeywordValuesForLocale()

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

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getLeastMaximum — 指定されたフィールドの、ローカルな最大値のうち、最小の値を返す

### 説明

オブジェクト指向型

public function IntlCalendar::getLeastMaximum(int `$field`): int|false

手続き型

function 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::getLocale

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getLocale — オブジェクトに関連付けられたロケールを取得する

### 説明

オブジェクト指向型

public function IntlCalendar::getLocale(int `$type`): string|false

手続き型

function 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::getMaximum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getMaximum — フィールドのグローバルな最大値を返す

### 説明

オブジェクト指向型

public function IntlCalendar::getMaximum(int `$field`): int|false

手続き型

function 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::getMinimalDaysInFirstWeek

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getMinimalDaysInFirstWeek — 特定の年や月における、最初の週の日数の最小値を返す

### 説明

オブジェクト指向型

public function IntlCalendar::getMinimalDaysInFirstWeek(): int|false

手続き型

function 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::getMinimum

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getMinimum — フィールドのグローバルな最小値を返す

### 説明

オブジェクト指向型

public function IntlCalendar::getMinimum(int `$field`): int|false

手続き型

function intlcal_get_minimum(IntlCalendar `$calendar`, int `$field`): int|false

この特定のカレンダーにおける、 フィールドのグローバルな最小値を取得します。 この値は IntlCalendar::getActualMinimum() が返す値に等しいか、より小さい値、 または IntlCalendar::getGreatestMinimum() が返す値に等しいか、より小きい値になります。 グレゴリオ暦のカレンダーでは、 これらは(各フィールドについて)常に同じ値を返します。

### パラメータ

`calendar`
  IntlCalendar クラスのインスタンス。
`field`

  IntlCalendar の日付/時刻 フィールド定数 のいずれか。 `0` から `IntlCalendar::FIELD_COUNT` までの間の整数値です。

### 戻り値

フィールドの値を示す整数値を、フィールドの単位で返します。 失敗した場合に `false` を返します

# IntlCalendar::getNow

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getNow — 現在時刻を示す数値を取得する

### 説明

オブジェクト指向型

public static function IntlCalendar::getNow(): float

手続き型

function 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::getRepeatedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getRepeatedWallTimeOption — 繰り返される実時間を扱う際の振る舞いを取得する

### 説明

オブジェクト指向型

public function IntlCalendar::getRepeatedWallTimeOption(): int

手続き型

function 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::getSkippedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getSkippedWallTimeOption — スキップされた実時間を扱う際の振る舞いを取得する

### 説明

オブジェクト指向型

public function IntlCalendar::getSkippedWallTimeOption(): int

手続き型

function 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::getTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getTime — このオブジェクトが表す時刻を取得する

### 説明

オブジェクト指向型

public function IntlCalendar::getTime(): float|false

手続き型

function 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::getTimeZone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getTimeZone — オブジェクトのタイムゾーンを取得する

### 説明

オブジェクト指向型

public function IntlCalendar::getTimeZone(): IntlTimeZone|false

手続き型

function 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::getType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getType — カレンダーのタイプを取得する

### 説明

オブジェクト指向型

public function IntlCalendar::getType(): string

手続き型

function 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::getWeekendTransition

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::getWeekendTransition — 週末が開始/終了した日からの経過時間を取得する

### 説明

オブジェクト指向型

public function IntlCalendar::getWeekendTransition(int `$dayOfWeek`): int|false

手続き型

function 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::inDaylightTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::inDaylightTime — オブジェクトの時刻が夏時間かを調べる

### 説明

オブジェクト指向型

public function IntlCalendar::inDaylightTime(): bool

手続き型

function 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::isEquivalentTo

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isEquivalentTo — 別のカレンダーが、時刻を除いて等しいかを調べる

### 説明

オブジェクト指向型

public function IntlCalendar::isEquivalentTo(IntlCalendar `$other`): bool

手続き型

function 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::isLenient

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isLenient — 日付と時刻の解釈を「緩いモード」で行うかを取得する

### 説明

オブジェクト指向型

public function IntlCalendar::isLenient(): bool

手続き型

function 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::isSet

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isSet — フィールドが設定されているかを調べる

### 説明

オブジェクト指向型

public function IntlCalendar::isSet(int `$field`): bool

手続き型

function 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::isWeekend

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::isWeekend — ある日付/時刻が週末にあるかを調べる

### 説明

オブジェクト指向型

public function IntlCalendar::isWeekend(?float `$timestamp` = `null`): bool

手続き型

function 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::roll

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::roll — 次のフィールドを繰り上げずに、フィールドに値を加算する

### 説明

オブジェクト指向型

public function IntlCalendar::roll(int `$field`, int|bool `$value`): bool

手続き型

function 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::set

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::set — 時刻または複数の共通フィールドを一度に設定する

### 説明

オブジェクト指向型

public function IntlCalendar::set(int `$field`, int `$value`): true
public function IntlCalendar::set(
int `$year`,
int `$month`,
int `$dayOfMonth` = NULL,
int `$hour` = NULL,
int `$minute` = NULL,
int `$second` = NULL
): true

手続き型

function intlcal_set(IntlCalendar `$cal`, int `$field`, int `$value`): true
function 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 でした。
8.4.0 | このメソッドは非推奨となりました。 代わりに IntlCalendar::setDate() や IntlCalendar::setDateTime() を使用してください。

### 例

例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::setDate

(PHP 8 >= 8.3.0)

IntlCalendar::setDate — 日付のフィールドを設定する

### 説明

public function 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::setDateTime

(PHP 8 >= 8.3.0)

IntlCalendar::setDateTime — 日付と時刻のフィールドを設定する

### 説明

public function 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::setFirstDayOfWeek

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setFirstDayOfWeek — 週の始まりと見なされる曜日を設定する

### 説明

オブジェクト指向型

public function IntlCalendar::setFirstDayOfWeek(int `$dayOfWeek`): true

手続き型

function 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::setLenient

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setLenient — 日付/時刻の解釈を「緩いモード」にするかを設定する

### 説明

オブジェクト指向型

public function IntlCalendar::setLenient(bool `$lenient`): true

手続き型

function intlcal_set_lenient(IntlCalendar `$calendar`, bool `$lenient`): true

カレンダーを「緩いモード」にするかを設定します。 緩いモードでは、 範囲外の値はフィールドによっては受け入れられる可能性があります。 振る舞いは IntlCalendar::add() のそれに似ています (つまり、値が元に戻り、重要度が高いフィールドが繰り上がります)。 「緩いモード」がオフの場合、範囲外の値の場合はエラーが発生します。

### パラメータ

`calendar`
  IntlCalendar クラスのインスタンス。
`lenient`

  「緩いモード」を有効にする場合は `true` を指定します。 オフにする場合は `false` を指定します。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.2.0 | 戻り値の型が、`true` になりました。これより前のバージョンでは、bool でした。

### 例

IntlCalendar::isLenient() の例を参照ください。

# IntlCalendar::setMinimalDaysInFirstWeek

(PHP 5 >= 5.5.1, PHP 7, PHP 8)

IntlCalendar::setMinimalDaysInFirstWeek — 特定の年や月における、最初の週の日数の最小値を設定する

### 説明

オブジェクト指向型

public function IntlCalendar::setMinimalDaysInFirstWeek(int `$days`): true

手続き型

function 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::setRepeatedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setRepeatedWallTimeOption — 負のタイムゾーンオフセットを適用した際に、繰り返される実時間をどう扱うかを設定する

### 説明

オブジェクト指向型

public function IntlCalendar::setRepeatedWallTimeOption(int `$option`): true

手続き型

function 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::setSkippedWallTimeOption

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setSkippedWallTimeOption — 正のタイムゾーンオフセットを適用した際に、スキップされる実時間をどう扱うかを設定する

### 説明

オブジェクト指向型

public function IntlCalendar::setSkippedWallTimeOption(int `$option`): true

手続き型

function 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::setTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setTime — エポックからのカレンダーの時刻をミリ秒単位で設定する

### 説明

オブジェクト指向型

public function IntlCalendar::setTime(float `$timestamp`): bool

手続き型

function 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 avancée d’Europe de l’Ouest
    dimanche 27 octobre 2013 01:30:00 heure avancée d’Europe de l’Ouest
    dimanche 27 octobre 2013 01:30:00 heure normale d’Europe de l’Ouest

# IntlCalendar::setTimeZone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlCalendar::setTimeZone — このカレンダーで使うタイムゾーンを設定する

### 説明

オブジェクト指向型

public function IntlCalendar::setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

手続き型

function 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` を返します。

### 例

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

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

    sábado, 1 de junio de 2013 12:00:00 Hora de verano de Europa occidental
    (instant 1370084400000)
    sábado, 1 de junio de 2013 11:00:00 GMT
    (instant 1370084400000)
    sábado, 1 de junio de 2013 14:33:00 GMT+03:33
    (instant 1370084400000)

# IntlCalendar::toDateTime

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a2)

IntlCalendar::toDateTime — IntlCalendar を DateTime オブジェクトに変換する

### 説明

オブジェクト指向型

public function IntlCalendar::toDateTime(): DateTime|false

手続き型

function 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 オブジェクトを返す

## 目次

- 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 クラス

(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 function __construct(IntlTimeZone `$tz` = ?, string `$locale` = ?)
public function __construct(int `$timeZoneOrYear`, int `$localeOrMonth`, int `$dayOfMonth`)
public function __construct(
int `$timeZoneOrYear`,
int `$localeOrMonth`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
int `$second` = ?
)
public static function createFromDate(int `$year`, int `$month`, int `$dayOfMonth`): static
public static function createFromDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): static
public function getGregorianChange(): float
public function isLeapYear(int `$year`): bool
public function setGregorianChange(float `$timestamp`): bool
/* 継承したメソッド */
public function IntlCalendar::add(int `$field`, int `$value`): bool
public function IntlCalendar::after(IntlCalendar `$other`): bool
public function IntlCalendar::before(IntlCalendar `$other`): bool
public function IntlCalendar::clear(?int `$field` = `null`): true
public static function IntlCalendar::createInstance(IntlTimeZone|DateTimeZone|string|null `$timezone` = `null`, ?string `$locale` = `null`): ?IntlCalendar
public function IntlCalendar::equals(IntlCalendar `$other`): bool
public function IntlCalendar::fieldDifference(float `$timestamp`, int `$field`): int|false
public static function IntlCalendar::fromDateTime(DateTime|string `$datetime`, ?string `$locale` = `null`): ?IntlCalendar
public function IntlCalendar::get(int `$field`): int|false
public function IntlCalendar::getActualMaximum(int `$field`): int|false
public function IntlCalendar::getActualMinimum(int `$field`): int|false
public static function IntlCalendar::getAvailableLocales(): array
public function IntlCalendar::getDayOfWeekType(int `$dayOfWeek`): int|false
public function IntlCalendar::getErrorCode(): int|false
public function IntlCalendar::getErrorMessage(): string|false
public function IntlCalendar::getFirstDayOfWeek(): int|false
public function IntlCalendar::getGreatestMinimum(int `$field`): int|false
public static function IntlCalendar::getKeywordValuesForLocale(string `$keyword`, string `$locale`, bool `$onlyCommon`): IntlIterator|false
public function IntlCalendar::getLeastMaximum(int `$field`): int|false
public function IntlCalendar::getLocale(int `$type`): string|false
public function IntlCalendar::getMaximum(int `$field`): int|false
public function IntlCalendar::getMinimalDaysInFirstWeek(): int|false
public function IntlCalendar::getMinimum(int `$field`): int|false
public static function IntlCalendar::getNow(): float
public function IntlCalendar::getRepeatedWallTimeOption(): int
public function IntlCalendar::getSkippedWallTimeOption(): int
public function IntlCalendar::getTime(): float|false
public function IntlCalendar::getTimeZone(): IntlTimeZone|false
public function IntlCalendar::getType(): string
public function IntlCalendar::getWeekendTransition(int `$dayOfWeek`): int|false
public function IntlCalendar::inDaylightTime(): bool
public function IntlCalendar::isEquivalentTo(IntlCalendar `$other`): bool
public function IntlCalendar::isLenient(): bool
public function IntlCalendar::isSet(int `$field`): bool
public function IntlCalendar::isWeekend(?float `$timestamp` = `null`): bool
public function IntlCalendar::roll(int `$field`, int|bool `$value`): bool
public function IntlCalendar::set(int `$field`, int `$value`): true
public function IntlCalendar::set(
int `$year`,
int `$month`,
int `$dayOfMonth` = NULL,
int `$hour` = NULL,
int `$minute` = NULL,
int `$second` = NULL
): true
public function IntlCalendar::setDate(int `$year`, int `$month`, int `$dayOfMonth`): void
public function IntlCalendar::setDateTime(
int `$year`,
int `$month`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
?int `$second` = `null`
): void
public function IntlCalendar::setFirstDayOfWeek(int `$dayOfWeek`): true
public function IntlCalendar::setLenient(bool `$lenient`): true
public function IntlCalendar::setMinimalDaysInFirstWeek(int `$days`): true
public function IntlCalendar::setRepeatedWallTimeOption(int `$option`): true
public function IntlCalendar::setSkippedWallTimeOption(int `$option`): true
public function IntlCalendar::setTime(float `$timestamp`): bool
public function IntlCalendar::setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool
public function IntlCalendar::toDateTime(): DateTime|false
}

# IntlGregorianCalendar::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::__construct — グレゴリオ暦の Calendar クラスを作成する

### 説明

public function IntlGregorianCalendar::__construct(IntlTimeZone `$tz` = ?, string `$locale` = ?)
public function IntlGregorianCalendar::__construct(int `$timeZoneOrYear`, int `$localeOrMonth`, int `$dayOfMonth`)
public function IntlGregorianCalendar::__construct(
int `$timeZoneOrYear`,
int `$localeOrMonth`,
int `$dayOfMonth`,
int `$hour`,
int `$minute`,
int `$second` = ?
)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`tz`

`locale`

`timeZoneOrYear`

`localeOrMonth`

`dayOfMonth`

`hour`

`minute`

`second`

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | このコンストラクタは非推奨となりました。 代わりに IntlGregorianCalendar::createFromDate() や IntlGregorianCalendar::createFromDateTime() を使用してください。

# IntlGregorianCalendar::createFromDate

(PHP 8 >= 8.3.0)

IntlGregorianCalendar::createFromDate — 日付の情報から、新しい IntlGregorianCalendar のインスタンスを作成する

### 説明

public static function 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::createFromDateTime

(PHP 8 >= 8.3.0)

IntlGregorianCalendar::createFromDateTime — 日付と時刻の値から、新しい IntlGregorianCalendar のインスタンスを作成する

### 説明

public static function 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::getGregorianChange

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::getGregorianChange — グレゴリオ暦への切換え日を取得する

### 説明

public function IntlGregorianCalendar::getGregorianChange(): float

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

切替日を返します。

# IntlGregorianCalendar::isLeapYear

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::isLeapYear — 指定された年がうるう年かを判定する

### 説明

public function IntlGregorianCalendar::isLeapYear(int `$year`): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`year`

### 戻り値

うるう年の場合、`true` を返します。 そうでない場合や、失敗した場合は `false` を返します。

# IntlGregorianCalendar::setGregorianChange

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlGregorianCalendar::setGregorianChange — グレゴリオ暦への切換え日を設定する

### 説明

public function IntlGregorianCalendar::setGregorianChange(float `$timestamp`): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`timestamp`

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

## 目次

- IntlGregorianCalendar::__construct — グレゴリオ暦の Calendar クラスを作成する
- IntlGregorianCalendar::createFromDate — 日付の情報から、新しい IntlGregorianCalendar のインスタンスを作成する
- IntlGregorianCalendar::createFromDateTime — 日付と時刻の値から、新しい IntlGregorianCalendar のインスタンスを作成する
- IntlGregorianCalendar::getGregorianChange — グレゴリオ暦への切換え日を取得する
- IntlGregorianCalendar::isLeapYear — 指定された年がうるう年かを判定する
- IntlGregorianCalendar::setGregorianChange — グレゴリオ暦への切換え日を設定する

# 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 function __construct()
public static function countEquivalentIDs(string `$timezoneId`): int|false
public static function createDefault(): IntlTimeZone
public static function createEnumeration(string|int|null `$countryOrRawOffset` = `null`): IntlIterator|false
public static function createTimeZone(string `$timezoneId`): ?IntlTimeZone
public static function createTimeZoneIDEnumeration(int `$type`, ?string `$region` = `null`, ?int `$rawOffset` = `null`): IntlIterator|false
public static function fromDateTimeZone(DateTimeZone `$timezone`): ?IntlTimeZone
public static function getCanonicalID(string `$timezoneId`, bool `&$isSystemId` = `null`): string|false
public function getDisplayName(bool `$dst` = `false`, int `$style` = `IntlTimeZone::DISPLAY_LONG`, ?string `$locale` = `null`): string|false
public function getDSTSavings(): int
public static function getEquivalentID(string `$timezoneId`, int `$offset`): string|false
public function getErrorCode(): int|false
public function getErrorMessage(): string|false
public static function getGMT(): IntlTimeZone
public static function getIanaID(string `$timezoneId`): string|false
public function getID(): string|false
public static function getIDForWindowsID(string `$timezoneId`, ?string `$region` = `null`): string|false
public function getOffset(
float `$timestamp`,
bool `$local`,
int `&$rawOffset`,
int `&$dstOffset`
): bool
public function getRawOffset(): int
public static function getRegion(string `$timezoneId`): string|false
public static function getTZDataVersion(): string|false
public static function getUnknown(): IntlTimeZone
public static function getWindowsID(string `$timezoneId`): string|false
public function hasSameRules(IntlTimeZone `$other`): bool
public function toDateTimeZone(): DateTimeZone|false
public function useDaylightTime(): bool
}

## 定義済み定数

`IntlTimeZone::DISPLAY_SHORT` int

`IntlTimeZone::DISPLAY_LONG` int

`IntlTimeZone::DISPLAY_SHORT_GENERIC` int

`IntlTimeZone::DISPLAY_LONG_GENERIC` int

`IntlTimeZone::DISPLAY_SHORT_GMT` int

`IntlTimeZone::DISPLAY_LONG_GMT` int

`IntlTimeZone::DISPLAY_SHORT_COMMONLY_USED` int

`IntlTimeZone::DISPLAY_GENERIC_LOCATION` int

`IntlTimeZone::TYPE_ANY` int

`IntlTimeZone::TYPE_CANONICAL` int

`IntlTimeZone::TYPE_CANONICAL_LOCATION` int

## 変更履歴

バージョン | 説明
--- | ---
8.4.0 | クラス定数が型付けされました。

# IntlTimeZone::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

IntlTimeZone::__construct — インスタンス化を禁止するためのprivateなコンストラクタ

### 説明

private function IntlTimeZone::__construct()

### パラメータ

この関数にはパラメータはありません。

# 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 function IntlTimeZone::countEquivalentIDs(string `$timezoneId`): int|false

手続き型:

function intltz_count_equivalent_ids(string `$timezoneId`): int|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`timezoneId`

### 戻り値

# 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 function IntlTimeZone::createDefault(): IntlTimeZone

手続き型:

function intltz_create_default(): IntlTimeZone

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# 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 function IntlTimeZone::createEnumeration(string|int|null `$countryOrRawOffset` = `null`): IntlIterator|false

手続き型:

function intltz_create_enumeration(string|int|null `$countryOrRawOffset` = `null`): IntlIterator|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`countryOrRawOffset`

### 戻り値

# 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 function IntlTimeZone::createTimeZone(string `$timezoneId`): ?IntlTimeZone

手続き型:

function intltz_create_time_zone(string `$timezoneId`): ?IntlTimeZone

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`timezoneId`

### 戻り値

# 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 function IntlTimeZone::createTimeZoneIDEnumeration(int `$type`, ?string `$region` = `null`, ?int `$rawOffset` = `null`): IntlIterator|false

手続き型:

function intltz_create_time_zone_id_enumeration(int `$type`, ?string `$region` = `null`, ?int `$rawOffset` = `null`): IntlIterator|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`type`

`region`

`rawOffset`

### 戻り値

IntlIterator を返します。 失敗した場合に `false` を返します.

# 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 function IntlTimeZone::fromDateTimeZone(DateTimeZone `$timezone`): ?IntlTimeZone

手続き型:

function intltz_from_date_time_zone(DateTimeZone `$timezone`): ?IntlTimeZone

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`timezone`

### 戻り値

# 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 function IntlTimeZone::getCanonicalID(string `$timezoneId`, bool `&$isSystemId` = `null`): string|false

手続き型:

function intltz_get_canonical_id(string `$timezoneId`, bool `&$isSystemId` = `null`): string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`timezoneId`

`isSystemId`

### 戻り値

# 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 function IntlTimeZone::getDisplayName(bool `$dst` = `false`, int `$style` = `IntlTimeZone::DISPLAY_LONG`, ?string `$locale` = `null`): string|false

手続き型:

function intltz_get_display_name(
IntlTimeZone `$timezone`,
bool `$dst` = `false`,
int `$style` = `IntlTimeZone::DISPLAY_LONG`,
?string `$locale` = `null`
): string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`dst`

`style`

`locale`

### 戻り値

# 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 function IntlTimeZone::getDSTSavings(): int

手続き型:

function intltz_get_dst_savings(IntlTimeZone `$timezone`): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# 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 function IntlTimeZone::getEquivalentID(string `$timezoneId`, int `$offset`): string|false

手続き型:

function intltz_get_equivalent_id(string `$timezoneId`, int `$offset`): string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`timezoneId`

`offset`

### 戻り値

# 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 function IntlTimeZone::getErrorCode(): int|false

手続き型:

function intltz_get_error_code(IntlTimeZone `$timezone`): int|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# 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 function IntlTimeZone::getErrorMessage(): string|false

手続き型:

function intltz_get_error_message(IntlTimeZone `$timezone`): string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# 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 function IntlTimeZone::getGMT(): IntlTimeZone

手続き型:

function intltz_get_gmt(): IntlTimeZone

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# IntlTimeZone::getIanaID

# intltz_get_iana_id

(PHP 8 >= 8.4.0)

IntlTimeZone::getIanaID -- intltz_get_iana_id — タイムゾーン識別子を、対応する IANA 識別子に変換する

### 説明

オブジェクト指向型 (method):

public static function IntlTimeZone::getIanaID(string `$timezoneId`): string|false

手続き型:

function intltz_get_iana_id(string `$timezoneId`): string|false

タイムゾーン識別子を、対応する IANA 識別子に変換します。たとえば、 `"GMT"` は `"Etc/GMT"` を返し、 `"US/Eastern"` は `"America/New_York"` を返します。

> 注意: この関数を使うには、ICU version ≥ 74 が必要です。

### パラメータ

`timezoneId`
  変換するタイムゾーン識別子。

### 戻り値

IANA のタイムゾーン識別子を string で返します。失敗した場合は `false` を返します。

### 参考

- intltz_get_id_for_windows_id() - Windows のタイムゾーンを、システムタイムゾーンに翻訳する
- intltz_get_windows_id() - システムタイムゾーンを、Windows のタイムゾーンに翻訳する
- intltz_create_time_zone() - 指定した 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 function IntlTimeZone::getID(): string|false

手続き型:

function intltz_get_id(IntlTimeZone `$timezone`): string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# 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 function IntlTimeZone::getIDForWindowsID(string `$timezoneId`, ?string `$region` = `null`): string|false

手続き型:

function 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 のタイムゾーンに翻訳する

# 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 function IntlTimeZone::getOffset(
float `$timestamp`,
bool `$local`,
int `&$rawOffset`,
int `&$dstOffset`
): bool

手続き型:

function intltz_get_offset(
IntlTimeZone `$timezone`,
float `$timestamp`,
bool `$local`,
int `&$rawOffset`,
int `&$dstOffset`
): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`timestamp`

`local`

`rawOffset`

`dstOffset`

### 戻り値

# 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 function IntlTimeZone::getRawOffset(): int

手続き型:

function intltz_get_raw_offset(IntlTimeZone `$timezone`): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# IntlTimeZone::getRegion

# intltz_get_region

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlTimeZone::getRegion -- intltz_get_region — 指定されたシステムタイムゾーンのIDから、地域コードを取得する

### 説明

オブジェクト指向型 (method):

public static function IntlTimeZone::getRegion(string `$timezoneId`): string|false

手続き型:

function intltz_get_region(string `$timezoneId`): string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`timezoneId`

### 戻り値

地域コードを返します。 失敗した場合に `false` を返します.

# 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 function IntlTimeZone::getTZDataVersion(): string|false

手続き型:

function intltz_get_tz_data_version(): string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# IntlTimeZone::getUnknown

# intltz_get_unknown

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlTimeZone::getUnknown -- intltz_get_unknown — "unknown" なタイムゾーンを取得する

### 説明

オブジェクト指向型 (method):

public static function IntlTimeZone::getUnknown(): IntlTimeZone

手続き型:

function intltz_get_unknown(): IntlTimeZone

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

IntlTimeZone を返します。 失敗した場合は `null` を返します。

# IntlTimeZone::getWindowsID

# intltz_get_windows_id

(PHP 7 >= 7.1.0, PHP 8)

IntlTimeZone::getWindowsID -- intltz_get_windows_id — システムタイムゾーンを、Windows のタイムゾーンに翻訳する

### 説明

オブジェクト指向型 (method):

public static function IntlTimeZone::getWindowsID(string `$timezoneId`): string|false

手続き型:

function 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::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 function IntlTimeZone::hasSameRules(IntlTimeZone `$other`): bool

手続き型:

function intltz_has_same_rules(IntlTimeZone `$timezone`, IntlTimeZone `$other`): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`other`

### 戻り値

# 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 function IntlTimeZone::toDateTimeZone(): DateTimeZone|false

手続き型:

function intltz_to_date_time_zone(IntlTimeZone `$timezone`): DateTimeZone|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# 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 function IntlTimeZone::useDaylightTime(): bool

手続き型:

function intltz_use_daylight_time(IntlTimeZone `$timezone`): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

## 目次

- 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::getIanaID — タイムゾーン識別子を、対応する IANA 識別子に変換する
- 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 クラス

(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 PATTERN;
public const int GREGORIAN;
public const int TRADITIONAL;
/* メソッド */
public function __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 function 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 function format(IntlCalendar|DateTimeInterface|array|string|int|float `$datetime`): string|false
public static function formatObject(IntlCalendar|DateTimeInterface `$datetime`, array|int|string|null `$format` = `null`, ?string `$locale` = `null`): string|false
public function getCalendar(): int|false
public function getDateType(): int|false
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false
public function getPattern(): string|false
public function getTimeType(): int|false
public function getTimeZoneId(): string|false
public function getCalendarObject(): IntlCalendar|false|null
public function getTimeZone(): IntlTimeZone|false
public function isLenient(): bool
public function localtime(string `$string`, int `&$offset` = `null`): array|false
public function parse(string `$string`, int `&$offset` = `null`): int|float|false
public function parseToCalendar(string `$string`, int `&$offset` = `null`): int|float|false
public function setCalendar(IntlCalendar|int|null `$calendar`): bool
public function setLenient(bool `$lenient`): void
public function setPattern(string `$pattern`): bool
public function setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool
}

## 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `IntlDateFormatter::PATTERN` が追加されました。

## 参考

- » ICU Date formatter

- » ICU Date formats

## 定義済み定数

これらの定数は、DateType や TimeType のコンストラクタでさまざまなフォーマットを指定するために使用します。

`IntlDateFormatter::NONE` int
  この要素を含まない
`IntlDateFormatter::FULL` int
  完全に指定した形式 (Tuesday, April 12, 1952 AD あるいは 3:30:42pm PST)
`IntlDateFormatter::LONG` int
  長い形式 (January 12, 1952 あるいは 3:30:32pm)
`IntlDateFormatter::MEDIUM` int
  中間の形式 (Jan 12, 1952)
`IntlDateFormatter::SHORT` int
  不可欠なデータのみを扱う最も省略した形式 (12/13/52 あるいは 3:30pm)
`IntlDateFormatter::RELATIVE_FULL` int
  `IntlDateFormatter::FULL` と同じですが、 昨日、今日、明日についてはそれぞれ、 `yesterday`, `today`, `tomorrow` になります。 PHP 8.0.0 以降で、`dateType` に限って利用可能です。
`IntlDateFormatter::RELATIVE_LONG` int
  `IntlDateFormatter::LONG` と同じですが、 昨日、今日、明日についてはそれぞれ、 `yesterday`, `today`, `tomorrow` になります。 PHP 8.0.0 以降で、`dateType` に限って利用可能です。
`IntlDateFormatter::RELATIVE_MEDIUM` int
  `IntlDateFormatter::MEDIUM` と同じですが、 昨日、今日、明日についてはそれぞれ、 `yesterday`, `today`, `tomorrow` になります。 PHP 8.0.0 以降で、`dateType` に限って利用可能です。
`IntlDateFormatter::RELATIVE_SHORT` int
  `IntlDateFormatter::SHORT` と同じですが、 昨日、今日、明日についてはそれぞれ、 `yesterday`, `today`, `tomorrow` になります。 PHP 8.0.0 以降で、`dateType` に限って利用可能です。
`IntlDateFormatter::PATTERN` int
  `pattern` で指定したパターンを使います。PHP 8.4.0 以降で利用可能です。

次の整数定数は、暦の種類を指定するものです。 これらの暦は、すべてグレゴリオ暦にもとづくものです。 グレゴリオ暦以外の暦はロケールで指定しなければなりません。 たとえば、 locale="hi@calendar=BUDDHIST" のようになります。

`IntlDateFormatter::TRADITIONAL` int
  非グレゴリオ暦
`IntlDateFormatter::GREGORIAN` int
  グレゴリオ暦

## 変更履歴

バージョン | 説明
--- | ---
8.4.0 | クラス定数が型付けされました。

# 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 function 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 function 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`
)

手続き型

function 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` を返します。

### エラー / 例外

`locale` が不正な場合、 ValueError をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `locale` が不正な場合、 ValueError をスローするように なりました。
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::format

# datefmt_format

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::format -- datefmt_format — 日付/時刻 の値を文字列としてフォーマットする

### 説明

オブジェクト指向型

public function IntlDateFormatter::format(IntlCalendar|DateTimeInterface|array|string|int|float `$datetime`): string|false

手続き型

function 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 intl 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 avancée 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::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 function IntlDateFormatter::formatObject(IntlCalendar|DateTimeInterface `$datetime`, array|int|string|null `$format` = `null`, ?string `$locale` = `null`): string|false

手続き型

function 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’été irlandaise
    array $format (none, full):
        17:05:06 heure d’été 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::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 function IntlDateFormatter::getCalendar(): int|false

手続き型

function 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::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 function IntlDateFormatter::getDateType(): int|false

手続き型

function 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::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 function IntlDateFormatter::getErrorCode(): int

手続き型

function 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::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 function IntlDateFormatter::getErrorMessage(): string

手続き型

function 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() - 指定したエラーコードが失敗を表すかどうかを調べる

# 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 function IntlDateFormatter::getLocale(int `$type` = `ULOC_ACTUAL_LOCALE`): string|false

手続き型

function 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::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 function IntlDateFormatter::getPattern(): string|false

手続き型

function 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::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 function IntlDateFormatter::getTimeType(): int|false

手続き型

function 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::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 function IntlDateFormatter::getTimeZoneId(): string|false

手続き型

function 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::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 function IntlDateFormatter::getCalendarObject(): IntlCalendar|false|null

手続き型

function 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::getTimeZone

# datefmt_get_timezone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::getTimeZone -- datefmt_get_timezone — タイムゾーンを取得する

### 説明

オブジェクト指向型

public function IntlDateFormatter::getTimeZone(): IntlTimeZone|false

手続き型

function 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::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 function IntlDateFormatter::isLenient(): bool

手続き型

function 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::localtime

# datefmt_localtime

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::localtime -- datefmt_localtime — 文字列をパースして、フィールドベースの時刻値にする

### 説明

オブジェクト指向型

public function IntlDateFormatter::localtime(string `$string`, int `&$offset` = `null`): array|false

手続き型

function 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 at 4:00:00 PM Pacific Standard Time', $offset);
    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 at 4:00:00 PM Pacific Standard Time', $offset);
    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 : 69 ,
    tm_mday : 31 , tm_wday : 3 , 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::parse

# datefmt_parse

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::parse -- datefmt_parse — 文字列をパースしてタイムスタンプにする

### 説明

オブジェクト指向型

public function IntlDateFormatter::parse(string `$string`, int `&$offset` = `null`): int|float|false

手続き型

function 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() - 直近の操作のエラーテキストを取得する

# IntlDateFormatter::parseToCalendar

(PHP 8 >= 8.4.0)

IntlDateFormatter::parseToCalendar — 文字列をパースしてタイムスタンプにし、使用中のカレンダーを更新する

### 説明

public function IntlDateFormatter::parseToCalendar(string `$string`, int `&$offset` = `null`): int|float|false

`string` を時間に変換します。`offset` からパースを開始し、入力値を可能な限り使用します。

このメソッドは IntlDateFormatter::parse() と同様に動作しますが、パースした `string` に含まれるタイムゾーン情報に応じて、フォーマッターのタイムゾーンが更新される点が異なります。

### パラメータ

`string`
  時間に変換する文字列。
`offset`
  `string` のパースを開始する位置 (ゼロから数えます)。 `string` を最後まで処理してもエラーが発生しなかった場合、 `offset` は -1 となります。それ以外の場合は、 パースが終了した (そしてエラーが発生した) 位置となります。 パースが失敗した場合、この変数にはその終了位置が格納されます。 `offset` > `strlen($string)` の場合、パースは即時に失敗します。

### 戻り値

タイムスタンプとしてパースされた値を返します。 パースできなかった場合は `false` を返します。

### 例

例1 IntlDateFormatter::parseToCalendar() の例

    <?php
    $fmt = new IntlDateFormatter(
        'en_US',
        IntlDateFormatter::FULL,
        IntlDateFormatter::FULL,
        'America/Los_Angeles',
        IntlDateFormatter::GREGORIAN
    );
    echo $fmt->parseToCalendar('Wednesday, December 20, 1989 at 4:00:00 PM Pacific Standard Time');
    ?>

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

    630201600

### 参考

- IntlDateFormatter::parse() - 文字列をパースしてタイムスタンプにする
- IntlDateFormatter::format() - 日付/時刻 の値を文字列としてフォーマットする
- IntlDateFormatter::getErrorCode() - 直近の操作のエラーコードを取得する
- IntlDateFormatter::getErrorMessage() - 直近の操作のエラーテキストを取得する

# 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 function IntlDateFormatter::setCalendar(IntlCalendar|int|null `$calendar`): bool

手続き型

function datefmt_set_calendar(IntlDateFormatter `$formatter`, IntlCalendar|int|null `$calendar`): bool

このフォーマッターが使用するカレンダーあるいはカレンダー型を設定します。

### パラメータ

`formatter`

  フォーマッターリソース。

`calendar`

  使用する カレンダー型 (デフォルトは `IntlDateFormatter::GREGORIAN` で、 `null` を指定した場合にもこれを使います)、あるいは IntlCalendar オブジェクト。

  IntlCalendar オブジェクトが渡された場合は、それをクローンします。 引数として渡したオブジェクトは、何も変更されません。

  フォーマッターのタイムゾーンを残すのは IntlCalendar オブジェクトが渡されなかった場合だけで、 このオブジェクトが渡された場合は新しいタイムゾーンを利用します。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
PECL intl 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::setLenient

# datefmt_set_lenient

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

IntlDateFormatter::setLenient -- datefmt_set_lenient — パーサーの寛大さを設定する

### 説明

オブジェクト指向型

public function IntlDateFormatter::setLenient(bool `$lenient`): void

手続き型

function 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::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 function IntlDateFormatter::setPattern(string `$pattern`): bool

手続き型

function 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::setTimeZone

# datefmt_set_timezone

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL intl >= 3.0.0)

IntlDateFormatter::setTimeZone -- datefmt_set_timezone — タイムゾーンを設定する

### 説明

オブジェクト指向型

public function IntlDateFormatter::setTimeZone(IntlTimeZone|DateTimeZone|string|null `$timezone`): bool

手続き型

function 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() - タイムゾーンを取得する

## 目次

- 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::parseToCalendar — 文字列をパースしてタイムスタンプにし、使用中のカレンダーを更新する
- IntlDateFormatter::setCalendar — Formatter が使うカレンダー型を設定する
- IntlDateFormatter::setLenient — パーサーの寛大さを設定する
- IntlDateFormatter::setPattern — IntlDateFormatter が使用するパターンを設定する
- IntlDateFormatter::setTimeZone — タイムゾーンを設定する

# 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 function __construct(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`)
public function count(): int
public static function create(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`): ?ResourceBundle
public function get(string|int `$index`, bool `$fallback` = `true`): ResourceBundle|array|string|int|null
public function getErrorCode(): int
public function getErrorMessage(): string
public static function getLocales(string `$bundle`): array|false
}

## 変更履歴

バージョン | 説明
--- | ---
8.0.0 | ResourceBundle は、 IteratorAggregate を実装しました。 これより前のバージョンでは、 Traversable を代わりに実装していました。
7.4.0 | ResourceBundle は、 Countable を新たに実装しました。

## 参考

- » ICU Resource Management
- » ICU Data

# ResourceBundle::count

# resourcebundle_count

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::count -- resourcebundle_count — バンドル内の要素数を取得する

### 説明

オブジェクト指向型

public function ResourceBundle::count(): int

手続き型

function 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::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 function ResourceBundle::create(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`): ?ResourceBundle

手続き型

function resourcebundle_create(?string `$locale`, ?string `$bundle`, bool `$fallback` = `true`): ?ResourceBundle

オブジェクト指向型 (コンストラクタ):

public function 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::get

# resourcebundle_get

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::get -- resourcebundle_get — バンドルからデータを取得する

### 説明

オブジェクト指向型

public function ResourceBundle::get(string|int `$index`, bool `$fallback` = `true`): ResourceBundle|array|string|int|null

手続き型

function resourcebundle_get(ResourceBundle `$bundle`, string|int `$index`, bool `$fallback` = `true`): ResourceBundle|array|string|int|null

インデックスあるいは文字列キーを指定して、バンドルからデータを取得します。

### パラメータ

`bundle`

  ResourceBundle オブジェクト。

`index`

  データのインデックス。文字列あるいは整数値となります。

`fallback`

  ロケールが正確にマッチしなければ、 親のロケールにfallback することを許すかどうか

### 戻り値

指定したインデックスのデータ、あるいはエラー時に `null` を返します。 文字列、整数値、バイナリデータ文字列は、それぞれに対応する PHP の型として返します。 整数の配列は PHP の配列として返します。複雑な型は ResourceBundle オブジェクトとして返します。

### エラー / 例外

オフセットの型が不正な場合、TypeError を スローします。

`index` が string で空文字列の場合や、 int で 32 ビット整数に収まらない場合、 ValueError をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | オフセットの型が不正な場合、TypeError をスローするようになりました。 `index` が string で空文字列の場合や、 int で 32 ビット整数に収まらない場合、 ValueError をスローするようになりました。

### 例

例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::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 function ResourceBundle::getErrorCode(): int

手続き型

function 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::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 function ResourceBundle::getErrorMessage(): string

手続き型

function 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::getLocales

# resourcebundle_locales

(PHP 5 >= 5.3.2, PHP 7, PHP 8, PECL intl >= 2.0.0)

ResourceBundle::getLocales -- resourcebundle_locales — サポートするロケールを取得する

### 説明

オブジェクト指向型

public static function ResourceBundle::getLocales(string `$bundle`): array|false

手続き型

function 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() - バンドルからデータを取得する

## 目次

- ResourceBundle::count — バンドル内の要素数を取得する
- ResourceBundle::create — リソースバンドルを作成する
- ResourceBundle::get — バンドルからデータを取得する
- ResourceBundle::getErrorCode — バンドルの直近のエラーコードを取得する
- ResourceBundle::getErrorMessage — バンドルの直近のエラーメッセージを取得する
- ResourceBundle::getLocales — サポートするロケールを取得する

# 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 const int IGNORE_SPACE;
public const int CASE_INSENSITIVE;
public const int ADD_CASE_MAPPINGS;
public const int SIMPLE_CASE_INSENSITIVE;
/* メソッド */
public function __construct()
public function areConfusable(string `$string1`, string `$string2`, int `&$errorCode` = `null`): bool
public function isSuspicious(string `$string`, int `&$errorCode` = `null`): bool
public function setAllowedChars(string `$pattern`, int `$patternOptions` = 0): void
public function setAllowedLocales(string `$locales`): void
public function setChecks(int `$checks`): void
public function setRestrictionLevel(int `$level`): void
}

## 定義済み定数

`Spoofchecker::SINGLE_SCRIPT_CONFUSABLE` int

`Spoofchecker::MIXED_SCRIPT_CONFUSABLE` int

`Spoofchecker::WHOLE_SCRIPT_CONFUSABLE` int

`Spoofchecker::ANY_CASE` int

`Spoofchecker::SINGLE_SCRIPT` int

`Spoofchecker::INVISIBLE` int

`Spoofchecker::CHAR_LIMIT` int

`Spoofchecker::ASCII` int

`Spoofchecker::HIGHLY_RESTRICTIVE` int

`Spoofchecker::MODERATELY_RESTRICTIVE` int

`Spoofchecker::MINIMALLY_RESTRICTIVE` int

`Spoofchecker::UNRESTRICTIVE` int

`Spoofchecker::SINGLE_SCRIPT_RESTRICTIVE` int

`Spoofchecker::MIXED_NUMBERS` int

`Spoofchecker::HIDDEN_OVERLAY` int

`Spoofchecker::IGNORE_SPACE` int

`Spoofchecker::CASE_INSENSITIVE` int
  大文字小文字を区別しないマッチングを有効にします
`Spoofchecker::ADD_CASE_MAPPINGS` int

  セット内の各要素に対して、すべての大文字小文字のマッピングを追加します

`Spoofchecker::SIMPLE_CASE_INSENSITIVE` int
  大文字小文字を区別しないマッチングを有効にします

## 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `Spoofchecker::IGNORE_SPACE`、`Spoofchecker::CASE_INSENSITIVE`、 `Spoofchecker::ADD_CASE_MAPPINGS`、`Spoofchecker::SIMPLE_CASE_INSENSITIVE` が追加されました。
8.4.0 | クラス定数が型付けされました。
7.3.0 | Spoofchecker::setRestrictionLevel() で使うクラス定数、`Spoofchecker::ASCII`, `Spoofchecker::HIGHLY_RESTRICTIVE`, `Spoofchecker::MODERATELY_RESTRICTIVE`, `Spoofchecker::MINIMALLY_RESTRICTIVE`, `Spoofchecker::UNRESTRICTIVE`, `Spoofchecker::SINGLE_SCRIPT_RESTRICTIVE` が追加されました。

# Spoofchecker::areConfusable

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::areConfusable — 指定された文字列が、読み手を混乱させうるかをチェックする

### 説明

public function 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::__construct

(No version information available, might only be in Git)

Spoofchecker::__construct — コンストラクタ

### 説明

public function Spoofchecker::__construct()

Spoofchecker の新しいインスタンスを作成します。

### パラメータ

この関数にはパラメータはありません。

# Spoofchecker::isSuspicious

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::isSuspicious — 指定されたテキストに、疑わしい文字が含まれていないかをチェックする

### 説明

public function 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::setAllowedChars

(PHP 8 >= 8.4.0)

Spoofchecker::setAllowedChars — チェック時に許可する文字集合を設定する

### 説明

public function Spoofchecker::setAllowedChars(string `$pattern`, int `$patternOptions` = 0): void

これ以降のチェックで許容される文字を、 `pattern` で記述された集合に制限します。 この集合に含まれない文字が存在すると、 Spoofchecker::isSuspicious() はそれを疑わしいものとして報告します。

### パラメータ

`pattern`
  `UnicodeSet` パターン、 すなわち正規表現スタイルの文字クラスとして記述された文字集合。 `[` で始まり `]` で終わる必要があります。 たとえば `[a-z0-9]` のようにします。
`patternOptions`
  `pattern` をどのように解釈するかを制御するビットマスク。 `0` にするか、 `Spoofchecker::IGNORE_SPACE` を単独で指定するか、 あるいはそれと `Spoofchecker::CASE_INSENSITIVE`、 `Spoofchecker::ADD_CASE_MAPPINGS`、 `Spoofchecker::SIMPLE_CASE_INSENSITIVE` のいずれかひとつだけを組み合わせて指定しなければなりません。

### 戻り値

値を返しません。

### エラー / 例外

`pattern` が有効な文字集合のパターンでない場合や、 `patternOptions` がオプションの有効な組み合わせでない場合に、 ValueError をスローします。

### 例

例1 Spoofchecker::setAllowedChars() の例

    <?php
    $checker = new Spoofchecker();
    $checker->setAllowedChars('[a-z0-9]');

    var_dump($checker->isSuspicious('hello'));
    var_dump($checker->isSuspicious('héllo'));
    ?>

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

    bool(false)
    bool(true)

### 参考

- Spoofchecker::setAllowedLocales() - チェック時に使うロケールを設定する
- Spoofchecker::isSuspicious() - 指定されたテキストに、疑わしい文字が含まれていないかをチェックする

# Spoofchecker::setAllowedLocales

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::setAllowedLocales — チェック時に使うロケールを設定する

### 説明

public function Spoofchecker::setAllowedLocales(string `$locales`): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`locales`

### 戻り値

# Spoofchecker::setChecks

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Spoofchecker::setChecks — 実行するチェックを設定する

### 説明

public function 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::setRestrictionLevel

(PHP 7 >= 7.3.0, PHP 8)

Spoofchecker::setRestrictionLevel — 制限レベルを設定する

### 説明

public function 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` です。

### 戻り値

値を返しません。

## 目次

- Spoofchecker::areConfusable — 指定された文字列が、読み手を混乱させうるかをチェックする
- Spoofchecker::__construct — コンストラクタ
- Spoofchecker::isSuspicious — 指定されたテキストに、疑わしい文字が含まれていないかをチェックする
- Spoofchecker::setAllowedChars — チェック時に許可する文字集合を設定する
- Spoofchecker::setAllowedLocales — チェック時に使うロケールを設定する
- Spoofchecker::setChecks — 実行するチェックを設定する
- Spoofchecker::setRestrictionLevel — 制限レベルを設定する

# 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 function __construct()
public static function create(string `$id`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator
public static function createFromRules(string `$rules`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator
public function createInverse(): ?Transliterator
public function getErrorCode(): int
public function getErrorMessage(): string
public static function listIDs(): array|false
public function transliterate(string `$string`, int `$start` = 0, int `$end` = -1): string|false
}

## プロパティ

id

## 定義済み定数

`Transliterator::FORWARD` int

`Transliterator::REVERSE` int

## 変更履歴

バージョン | 説明
--- | ---
8.4.0 | クラス定数が型付けされました。
8.2.0 | プロパティ id は、readonly になりました。

# Transliterator::__construct

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::__construct — インスタンス化を拒否するために private にしたコンストラクタ

### 説明

final private function Transliterator::__construct()

このメソッドをコールしてはいけません。 new 演算子によるインスタンス化を拒否するために用意されたものです。

かわりに、ファクトリーメソッドである Transliterator::create() あるいは Transliterator::createFromRules() を使いましょう。

### パラメータ

この関数にはパラメータはありません。

### 参考

- Transliterator::create() - Transliterator を作成する
- Transliterator::createFromRules() - 規則に基づいた 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 function Transliterator::create(string `$id`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

手続き型

function 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::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 function Transliterator::createFromRules(string `$rules`, int `$direction` = `Transliterator::FORWARD`): ?Transliterator

手続き型

function 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::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 function Transliterator::createInverse(): ?Transliterator

手続き型

function transliterator_create_inverse(Transliterator `$transliterator`): ?Transliterator

逆方向の Transliterator をオープンします。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に Transliterator オブジェクト、失敗した場合に `null` を返します。

### 参考

- Transliterator::getErrorMessage() - 直近のエラーメッセージを取得する
- Transliterator::create() - 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 function Transliterator::getErrorCode(): int

手続き型

function transliterator_get_error_code(Transliterator `$transliterator`): int

この Transliterator の直近のエラーコードを取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`transliterator`

### 戻り値

成功した場合にエラーコードを返します。 エラーがない場合や失敗した場合は `false` を返します。

### 参考

- Transliterator::getErrorMessage() - 直近のエラーメッセージを取得する
- Transliterator::listIDs() - Transliterator の ID を取得する

# 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 function Transliterator::getErrorMessage(): string

手続き型

function transliterator_get_error_message(Transliterator `$transliterator`): string

この Transliterator の直近のエラーメッセージを取得します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`transliterator`

### 戻り値

成功した場合にエラーメッセージを返します。 エラーがない場合や失敗した場合は `false` を返します。

### 参考

- Transliterator::getErrorCode() - 直近のエラーコードを取得する
- Transliterator::listIDs() - 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 function Transliterator::listIDs(): array|false

手続き型

function 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::transliterate

# transliterator_transliterate

(PHP 5 >= 5.4.0, PHP 7, PHP 8, PECL intl >= 2.0.0)

Transliterator::transliterate -- transliterator_transliterate — 文字列を音訳する

### 説明

オブジェクト指向型

public function Transliterator::transliterate(string `$string`, int `$start` = 0, int `$end` = -1): string|false

手続き型

function 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 にしたコンストラクタ

## 目次

- Transliterator::__construct — インスタンス化を拒否するために private にしたコンストラクタ
- Transliterator::create — Transliterator を作成する
- Transliterator::createFromRules — 規則に基づいた Transliterator を作成する
- Transliterator::createInverse — 逆方向の Transliterator を作成する
- Transliterator::getErrorCode — 直近のエラーコードを取得する
- Transliterator::getErrorMessage — 直近のエラーメッセージを取得する
- Transliterator::listIDs — Transliterator の ID を取得する
- Transliterator::transliterate — 文字列を音訳する

# 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 function __construct()
public static function createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function createCodePointInstance(): IntlCodePointBreakIterator
public static function createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator
public function current(): int
public function first(): int
public function following(int `$offset`): int
public function getErrorCode(): int
public function getErrorMessage(): string
public function getLocale(int `$type`): string|false
public function getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator
public function getText(): ?string
public function isBoundary(int `$offset`): bool
public function last(): int
public function next(?int `$offset` = `null`): int
public function preceding(int `$offset`): int
public function previous(): int
public function setText(string `$text`): bool
}

## 定義済み定数

`IntlBreakIterator::DONE` int

`IntlBreakIterator::WORD_NONE` int

`IntlBreakIterator::WORD_NONE_LIMIT` int

`IntlBreakIterator::WORD_NUMBER` int

`IntlBreakIterator::WORD_NUMBER_LIMIT` int

`IntlBreakIterator::WORD_LETTER` int

`IntlBreakIterator::WORD_LETTER_LIMIT` int

`IntlBreakIterator::WORD_KANA` int

`IntlBreakIterator::WORD_KANA_LIMIT` int

`IntlBreakIterator::WORD_IDEO` int

`IntlBreakIterator::WORD_IDEO_LIMIT` int

`IntlBreakIterator::LINE_SOFT` int

`IntlBreakIterator::LINE_SOFT_LIMIT` int

`IntlBreakIterator::LINE_HARD` int

`IntlBreakIterator::LINE_HARD_LIMIT` int

`IntlBreakIterator::SENTENCE_TERM` int

`IntlBreakIterator::SENTENCE_TERM_LIMIT` int

`IntlBreakIterator::SENTENCE_SEP` int

`IntlBreakIterator::SENTENCE_SEP_LIMIT` int

## 変更履歴

バージョン | 説明
--- | ---
8.4.0 | クラス定数が型付けされました。
8.0.0 | IntlBreakIterator は、 IteratorAggregate を実装しました。 これより前のバージョンでは、 Traversable を代わりに実装していました。

# IntlBreakIterator::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::__construct — インスタンス化を禁止するためのprivateなコンストラクタ

### 説明

private function IntlBreakIterator::__construct()

IntlBreakIterator のインスタンスは、 static なファクトリメソッドのうちの一つを使って生成してください。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

### 参考

- IntlBreakIterator::createCharacterInstance() - 文字シーケンスの組み合わせの境界用にイテレータを作る
- IntlBreakIterator::createCodePointInstance() - コードポイントの境界用にイテレータを作る
- IntlBreakIterator::createLineInstance() - 論理的に可能な改行用にイテレータを作る
- IntlBreakIterator::createSentenceInstance() - 文末用にイテレータを作る
- IntlBreakIterator::createTitleInstance() - タイトル文字の区切り用にイテレータを作る
- IntlBreakIterator::createWordInstance() - 単語の区切り用にイテレータを作る

# IntlBreakIterator::createCharacterInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createCharacterInstance — 文字シーケンスの組み合わせの境界用にイテレータを作る

### 説明

public static function IntlBreakIterator::createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`locale`

### 戻り値

# IntlBreakIterator::createCodePointInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createCodePointInstance — コードポイントの境界用にイテレータを作る

### 説明

public static function IntlBreakIterator::createCodePointInstance(): IntlCodePointBreakIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# IntlBreakIterator::createLineInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createLineInstance — 論理的に可能な改行用にイテレータを作る

### 説明

public static function IntlBreakIterator::createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`locale`

### 戻り値

# IntlBreakIterator::createSentenceInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createSentenceInstance — 文末用にイテレータを作る

### 説明

public static function IntlBreakIterator::createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`locale`

### 戻り値

# IntlBreakIterator::createTitleInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createTitleInstance — タイトル文字の区切り用にイテレータを作る

### 説明

public static function IntlBreakIterator::createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`locale`

### 戻り値

# IntlBreakIterator::createWordInstance

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::createWordInstance — 単語の区切り用にイテレータを作る

### 説明

public static function IntlBreakIterator::createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`locale`

### 戻り値

# IntlBreakIterator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::current — 現在位置のインデックスを取得する

### 説明

public function IntlBreakIterator::current(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# IntlBreakIterator::first

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::first — テキスト内の最初の文字を場所を取得する

### 説明

public function IntlBreakIterator::first(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# IntlBreakIterator::following

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::following — 指定したオフセット以降の最初の境界までイテレータを進める

### 説明

public function IntlBreakIterator::following(int `$offset`): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`offset`

### 戻り値

# IntlBreakIterator::getErrorCode

# intl_get_error_code

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getErrorCode -- intl_get_error_code — このオブジェクトの直近のエラーコードを取得する

### 説明

オブジェクト指向型 (method):

public function IntlBreakIterator::getErrorCode(): int

手続き型:

function intl_get_error_code(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# IntlBreakIterator::getErrorMessage

# intl_get_error_message

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getErrorMessage -- intl_get_error_message — このオブジェクトの直近のエラーメッセージを取得する

### 説明

オブジェクト指向型 (method):

public function IntlBreakIterator::getErrorMessage(): string

手続き型:

function intl_get_error_message(): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# IntlBreakIterator::getLocale

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getLocale — このオブジェクトに関連づけられたロケールを取得する

### 説明

public function IntlBreakIterator::getLocale(int `$type`): string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`type`

### 戻り値

# IntlBreakIterator::getPartsIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getPartsIterator — 境界と境界の間の navigating fragments 用にイテレータを作る

### 説明

public function IntlBreakIterator::getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`type`

  オプションのキータイプ。可能な値は以下のとおりです:

  - `IntlPartsIterator::KEY_SEQUENTIAL` - デフォルト。シーケンシャルに増える整数をキーとして使います
  - `IntlPartsIterator::KEY_LEFT` - 現在のパートの左側のバイトオフセットをキーとして使います。
  - `IntlPartsIterator::KEY_RIGHT` - 現在のパートの右側のバイトオフセットをキーとして使います。

### 戻り値

# IntlBreakIterator::getText

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::getText — スキャンするテキストを取得する

### 説明

public function IntlBreakIterator::getText(): ?string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# IntlBreakIterator::isBoundary

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::isBoundary — あるオフセットが境界のオフセットかどうかを調べる

### 説明

public function IntlBreakIterator::isBoundary(int `$offset`): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`offset`

### 戻り値

# IntlBreakIterator::last

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::last — イテレータの位置を、最後の文字より後に設定する

### 説明

public function IntlBreakIterator::last(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# IntlBreakIterator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::next — イテレータを次の境界まで進める

### 説明

public function IntlBreakIterator::next(?int `$offset` = `null`): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`offset`

### 戻り値

# IntlBreakIterator::preceding

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::preceding — イテレータの位置を、指定したオフセット以前の最初の境界に設定する

### 説明

public function IntlBreakIterator::preceding(int `$offset`): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`offset`

### 戻り値

# IntlBreakIterator::previous

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::previous — イテレータの位置を、現在位置の直前の境界に設定する

### 説明

public function IntlBreakIterator::previous(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# IntlBreakIterator::setText

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlBreakIterator::setText — スキャンするテキストを設定する

### 説明

public function IntlBreakIterator::setText(string `$text`): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`text`

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.3.0 | この関数は、失敗時に `false` を返すようになりました。 これより前のバージョンでは `null` を返していました。

## 目次

- 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 クラス

(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 function __construct(string `$rules`, bool `$compiled` = `false`)
public function getBinaryRules(): string|false
public function getRules(): string|false
public function getRuleStatus(): int
public function getRuleStatusVec(): array|false
/* 継承したメソッド */
public static function IntlBreakIterator::createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createCodePointInstance(): IntlCodePointBreakIterator
public static function IntlBreakIterator::createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator
public function IntlBreakIterator::current(): int
public function IntlBreakIterator::first(): int
public function IntlBreakIterator::following(int `$offset`): int
public function IntlBreakIterator::getErrorCode(): int
public function IntlBreakIterator::getErrorMessage(): string
public function IntlBreakIterator::getLocale(int `$type`): string|false
public function IntlBreakIterator::getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator
public function IntlBreakIterator::getText(): ?string
public function IntlBreakIterator::isBoundary(int `$offset`): bool
public function IntlBreakIterator::last(): int
public function IntlBreakIterator::next(?int `$offset` = `null`): int
public function IntlBreakIterator::preceding(int `$offset`): int
public function IntlBreakIterator::previous(): int
public function IntlBreakIterator::setText(string `$text`): bool
}

# IntlRuleBasedBreakIterator::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::__construct — ルールセットから iterator を作成する

### 説明

public function IntlRuleBasedBreakIterator::__construct(string `$rules`, bool `$compiled` = `false`)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`rules`

`compiled`

### 戻り値

# IntlRuleBasedBreakIterator::getBinaryRules

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getBinaryRules — コンパイル済みのルールを、バイナリで取得する

### 説明

public function IntlRuleBasedBreakIterator::getBinaryRules(): string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# IntlRuleBasedBreakIterator::getRules

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getRules — このオブジェクトを作るのに使われているルールを取得する

### 説明

public function IntlRuleBasedBreakIterator::getRules(): string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# IntlRuleBasedBreakIterator::getRuleStatus

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getRuleStatus — 現在の境界位置を決めるルールから、ステータスの最大値を取得する

### 説明

public function IntlRuleBasedBreakIterator::getRuleStatus(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# IntlRuleBasedBreakIterator::getRuleStatusVec

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlRuleBasedBreakIterator::getRuleStatusVec — 現在の境界位置から定まるルールから、ステータス値を取得する

### 説明

public function IntlRuleBasedBreakIterator::getRuleStatusVec(): array|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

## 目次

- IntlRuleBasedBreakIterator::__construct — ルールセットから iterator を作成する
- IntlRuleBasedBreakIterator::getBinaryRules — コンパイル済みのルールを、バイナリで取得する
- IntlRuleBasedBreakIterator::getRules — このオブジェクトを作るのに使われているルールを取得する
- IntlRuleBasedBreakIterator::getRuleStatus — 現在の境界位置を決めるルールから、ステータスの最大値を取得する
- IntlRuleBasedBreakIterator::getRuleStatusVec — 現在の境界位置から定まるルールから、ステータス値を取得する

# 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 function getLastCodePoint(): int
/* 継承したメソッド */
public static function IntlBreakIterator::createCharacterInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createCodePointInstance(): IntlCodePointBreakIterator
public static function IntlBreakIterator::createLineInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createSentenceInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createTitleInstance(?string `$locale` = `null`): ?IntlBreakIterator
public static function IntlBreakIterator::createWordInstance(?string `$locale` = `null`): ?IntlBreakIterator
public function IntlBreakIterator::current(): int
public function IntlBreakIterator::first(): int
public function IntlBreakIterator::following(int `$offset`): int
public function IntlBreakIterator::getErrorCode(): int
public function IntlBreakIterator::getErrorMessage(): string
public function IntlBreakIterator::getLocale(int `$type`): string|false
public function IntlBreakIterator::getPartsIterator(string `$type` = `IntlPartsIterator::KEY_SEQUENTIAL`): IntlPartsIterator
public function IntlBreakIterator::getText(): ?string
public function IntlBreakIterator::isBoundary(int `$offset`): bool
public function IntlBreakIterator::last(): int
public function IntlBreakIterator::next(?int `$offset` = `null`): int
public function IntlBreakIterator::preceding(int `$offset`): int
public function IntlBreakIterator::previous(): int
public function IntlBreakIterator::setText(string `$text`): bool
}

# IntlCodePointBreakIterator::getLastCodePoint

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlCodePointBreakIterator::getLastCodePoint — イテレータを進めたり、戻したりした後に渡された、直近のコードポイントを取得する

### 説明

public function IntlCodePointBreakIterator::getLastCodePoint(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

## 目次

- IntlCodePointBreakIterator::getLastCodePoint — イテレータを進めたり、戻したりした後に渡された、直近のコードポイントを取得する

# IntlDatePatternGenerator クラス

(PHP 8 >= 8.1.0)

## はじめに

IntlDateFormatter で使われる、 地域化された 日付/時刻 のフォーマットパターン文字列を生成します。

## クラス概要

class IntlDatePatternGenerator {
/* メソッド */
public function __construct(?string `$locale` = `null`)
public static function create(?string `$locale` = `null`): ?IntlDatePatternGenerator
public function getBestPattern(string `$skeleton`): string|false
}

# IntlDatePatternGenerator::create

# IntlDatePatternGenerator::__construct

(PHP 8 >= 8.1.0)

IntlDatePatternGenerator::create -- IntlDatePatternGenerator::__construct — IntlDatePatternGenerator を作成する

### 説明

public static function IntlDatePatternGenerator::create(?string `$locale` = `null`): ?IntlDatePatternGenerator
public function IntlDatePatternGenerator::__construct(?string `$locale` = `null`)

IntlDatePatternGenerator のインスタンスを作成します。

### パラメータ

`locale`

  ロケールを指定します。 `null` を渡すと、 intl.default_locale の設定を使います。

### 戻り値

成功時に IntlDatePatternGenerator のインスタンスを返します。失敗時に `null` を返します。

# IntlDatePatternGenerator::getBestPattern

(PHP 8 >= 8.1.0)

IntlDatePatternGenerator::getBestPattern — もっとも適合した 日付/時刻 のフォーマットを決定する

### 説明

public function IntlDatePatternGenerator::getBestPattern(string `$skeleton`): string|false

特定のロケールにもっとも合致した 日付/時刻のフォーマットがどれかを決定します。

### パラメータ

`skeleton`

  スケルトンを指定します。

### 戻り値

成功時に IntlDateFormatter が受け入れる ICU の 日付/時刻 パターンを返します。 失敗した場合に `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

## 目次

- IntlDatePatternGenerator::create — IntlDatePatternGenerator を作成する
- IntlDatePatternGenerator::getBestPattern — もっとも適合した 日付/時刻 のフォーマットを決定する

# 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 function getBreakIterator(): IntlBreakIterator
/* 継承したメソッド */
public function IntlIterator::current(): mixed
public function IntlIterator::key(): mixed
public function IntlIterator::next(): void
public function IntlIterator::rewind(): void
public function IntlIterator::valid(): bool
}

## 定義済み定数

`IntlPartsIterator::KEY_SEQUENTIAL` int

`IntlPartsIterator::KEY_LEFT` int

`IntlPartsIterator::KEY_RIGHT` int

## 変更履歴

バージョン | 説明
--- | ---
8.4.0 | クラス定数が型付けされました。

# IntlPartsIterator::getBreakIterator

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlPartsIterator::getBreakIterator — この parts iterator の裏付けとなる、IntlBreakIterator を取得する

### 説明

public function IntlPartsIterator::getBreakIterator(): IntlBreakIterator

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

## 目次

- IntlPartsIterator::getBreakIterator — この parts iterator の裏付けとなる、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 function __construct(?string `$destination_encoding` = `null`, ?string `$source_encoding` = `null`)
public function convert(string `$str`, bool `$reverse` = `false`): string|false
public function fromUCallback(
int `$reason`,
array `$source`,
int `$codePoint`,
int `&$error`
): string|int|array|null
public static function getAliases(string `$name`): array|false|null
public static function getAvailable(): array
public function getDestinationEncoding(): string|false|null
public function getDestinationType(): int|false|null
public function getErrorCode(): int
public function getErrorMessage(): ?string
public function getSourceEncoding(): string|false|null
public function getSourceType(): int|false|null
public static function getStandards(): ?array
public function getSubstChars(): string|false|null
public static function reasonText(int `$reason`): string
public function setDestinationEncoding(string `$encoding`): bool
public function setSourceEncoding(string `$encoding`): bool
public function setSubstChars(string `$chars`): bool
public function toUCallback(
int `$reason`,
string `$source`,
string `$codeUnits`,
int `&$error`
): string|int|array|null
public static function transcode(
string `$str`,
string `$toEncoding`,
string `$fromEncoding`,
?array `$options` = `null`
): string|false
}

## 定義済み定数

`UConverter::REASON_UNASSIGNED` int

`UConverter::REASON_ILLEGAL` int

`UConverter::REASON_IRREGULAR` int

`UConverter::REASON_RESET` int

`UConverter::REASON_CLOSE` int

`UConverter::REASON_CLONE` int

`UConverter::UNSUPPORTED_CONVERTER` int

`UConverter::SBCS` int

`UConverter::DBCS` int

`UConverter::MBCS` int

`UConverter::LATIN_1` int

`UConverter::UTF8` int

`UConverter::UTF16_BigEndian` int

`UConverter::UTF16_LittleEndian` int

`UConverter::UTF32_BigEndian` int

`UConverter::UTF32_LittleEndian` int

`UConverter::EBCDIC_STATEFUL` int

`UConverter::ISO_2022` int

`UConverter::LMBCS_1` int

`UConverter::LMBCS_2` int

`UConverter::LMBCS_3` int

`UConverter::LMBCS_4` int

`UConverter::LMBCS_5` int

`UConverter::LMBCS_6` int

`UConverter::LMBCS_8` int

`UConverter::LMBCS_11` int

`UConverter::LMBCS_16` int

`UConverter::LMBCS_17` int

`UConverter::LMBCS_18` int

`UConverter::LMBCS_19` int

`UConverter::LMBCS_LAST` int

`UConverter::HZ` int

`UConverter::SCSU` int

`UConverter::ISCII` int

`UConverter::US_ASCII` int

`UConverter::UTF7` int

`UConverter::BOCU1` int

`UConverter::UTF16` int

`UConverter::UTF32` int

`UConverter::CESU8` int

`UConverter::IMAP_MAILBOX` int

## 変更履歴

バージョン | 説明
--- | ---
8.4.0 | クラス定数が型付けされました。

# UConverter::__construct

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::__construct — UConverter オブジェクトを作る

### 説明

public function UConverter::__construct(?string `$destination_encoding` = `null`, ?string `$source_encoding` = `null`)

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`destination_encoding`

`source_encoding`

### 戻り値

# UConverter::convert

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::convert — ある文字セットから別の文字セットに文字列を変換する

### 説明

public function UConverter::convert(string `$str`, bool `$reverse` = `false`): string|false

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`str`

`reverse`

### 戻り値

# UConverter::fromUCallback

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::fromUCallback — デフォルトの "from" コールバック関数

### 説明

public function UConverter::fromUCallback(
int `$reason`,
array `$source`,
int `$codePoint`,
int `&$error`
): string|int|array|null

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`reason`

`source`

`codePoint`

`error`

### 戻り値

# UConverter::getAliases

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getAliases — 指定した名前のエイリアスを取得する

### 説明

public static function UConverter::getAliases(string `$name`): array|false|null

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`name`

### 戻り値

# UConverter::getAvailable

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getAvailable — 利用可能なコンバーター名を取得する

### 説明

public static function UConverter::getAvailable(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# UConverter::getDestinationEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getDestinationEncoding — 変換先エンコーディングを取得する

### 説明

public function UConverter::getDestinationEncoding(): string|false|null

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# UConverter::getDestinationType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getDestinationType — 変換先のコンバーターの型を取得する

### 説明

public function UConverter::getDestinationType(): int|false|null

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# 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 function UConverter::getErrorCode(): int

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# UConverter::getErrorMessage

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getErrorMessage — 直近のエラーメッセージを取得する

### 説明

public function UConverter::getErrorMessage(): ?string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# UConverter::getSourceEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getSourceEncoding — 変換元エンコーディングを取得する

### 説明

public function UConverter::getSourceEncoding(): string|false|null

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# UConverter::getSourceType

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getSourceType — 変換元のコンバーターの型を取得する

### 説明

public function UConverter::getSourceType(): int|false|null

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# UConverter::getStandards

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getStandards — コンバーター名に対応する標準を取得する

### 説明

public static function UConverter::getStandards(): ?array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# UConverter::getSubstChars

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::getSubstChars — 置換文字を取得する

### 説明

public function UConverter::getSubstChars(): string|false|null

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# UConverter::reasonText

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::reasonText — コールバックの理由を表す文字列を取得する

### 説明

public static function UConverter::reasonText(int `$reason`): string

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`reason`

### 戻り値

# UConverter::setDestinationEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::setDestinationEncoding — 変換先エンコーディングを設定する

### 説明

public function UConverter::setDestinationEncoding(string `$encoding`): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`encoding`

### 戻り値

# UConverter::setSourceEncoding

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::setSourceEncoding — 変換元エンコーディングを設定する

### 説明

public function UConverter::setSourceEncoding(string `$encoding`): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`encoding`

### 戻り値

# UConverter::setSubstChars

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::setSubstChars — 置換文字を設定する

### 説明

public function UConverter::setSubstChars(string `$chars`): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`chars`

### 戻り値

# UConverter::toUCallback

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::toUCallback — デフォルトの "to" コールバック関数

### 説明

public function UConverter::toUCallback(
int `$reason`,
string `$source`,
string `$codeUnits`,
int `&$error`
): string|int|array|null

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`reason`

`source`

`codeUnits`

`error`

### 戻り値

# UConverter::transcode

(PHP 5 >= 5.5.0, PHP 7, PHP 8, PECL >= 3.0.0a1)

UConverter::transcode — ある文字エンコーディングから別の文字エンコーディングに文字列を変換する

### 説明

public static function 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"; // 'Zoë' 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() - ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する

## 目次

- 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

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_extract — デフォルトの書記素クラスタシーケンスをテキストバッファから取り出す関数。 テキストは UTF-8 でエンコードされている必要があります

### 説明

手続き型

function 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_str_split

(PHP 8 >= 8.4.0)

grapheme_str_split — 書記素クラスターを受け取り、文字の配列を返す

### 説明

function grapheme_str_split(string `$string`, int `$length` = 1): array|false

この関数は文字の配列を返します。 これは str_split() に書記素クラスターのサポートを追加したものです。 `length` を指定すると、文字列は指定された数の 書記素クラスターに分割されます。

### パラメータ

`string`

  書記素クラスターまたはチャンクに分割するstring。 `string` はUTF-8でなければなりません。

`length`

  配列の各要素が `length` 書記素クラスターで構成されます。

### 戻り値

grapheme_str_split() は文字列の配列を返します。 失敗した場合に `false` を返します。

### エラー / 例外

`length` が `1` 未満のとき、 ValueError がスローされます。

### 参考

- str_split() - 文字列を配列に変換する
- mb_str_split() - マルチバイト文字列を受取り、文字の配列を返す
- » Unicode Text Segmentation: Grapheme Cluster Boundaries

# grapheme_stripos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_stripos — 大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける

### 説明

手続き型

function grapheme_stripos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
string `$locale` = ""
): int|false

大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つけます。

### パラメータ

`haystack`

  探す対象となる文字列。正しい形式の UTF-8 でなければなりません。

`needle`

  探したい文字列。正しい形式の UTF-8 でなければなりません。

`offset`

  オプションの `offset` パラメータで、`haystack` のどの位置 (バイト数や文字数ではなく、書記素単位) から探し始めるのかを指定します。 負の値を指定した場合は、文字列の末尾からのオフセットとみなします。 `offset` の値にかかわらず、返される値は常に `haystack` の先頭からの位置になります。

`locale`
  使用するロケール。

### 戻り値

位置を表す整数値を返します。`needle` が見つからない場合は grapheme_stripos() は `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | オプションのパラメータ `locale` が追加されました。
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

# grapheme_stristr

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_stristr — 大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所以降の部分文字列を返す

### 説明

手続き型

function grapheme_stristr(
string `$haystack`,
string `$needle`,
bool `$beforeNeedle` = `false`,
string `$locale` = ""
): string|false

大文字小文字を区別せず、`haystack` 文字列の中で needle が最初に登場した場所を含めてそれ以降の部分文字列を返します。

### パラメータ

`haystack`

  入力文字列。正しい形式の UTF-8 でなければなりません。

`needle`

  探したい文字列。正しい形式の UTF-8 でなければなりません。

`beforeNeedle`

  `true` の場合、grapheme_stristr() は needle が最初に登場した場所より前の、 `haystack` の部分文字列を返します (`needle` は含めません)。

`locale`
  使用するロケール。

### 戻り値

`haystack` の部分文字列、あるいは `needle` が見つからなかった場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | オプションのパラメータ `locale` が追加されました。

### 例

例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_strlen

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strlen — 書記素単位で文字列の長さを取得する

### 説明

手続き型

function grapheme_strlen(string `$string`): int|false|null

書記素単位 (バイト数や文字数ではありません) で文字列の長さを取得します。

### パラメータ

`string`

  長さを調べたい文字列。正しい形式の UTF-8 でなければなりません。

### 戻り値

成功した場合に文字列の長さを返します。 失敗した場合は `null` または `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_strpos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strpos — 文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける

### 説明

手続き型

function grapheme_strpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
string `$locale` = ""
): int|false

文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つけます。

### パラメータ

`haystack`

  探す対象となる文字列。正しい形式の UTF-8 でなければなりません。

`needle`

  探したい文字列。正しい形式の UTF-8 でなければなりません。

`offset`

  オプションの `offset` パラメータで、`haystack` のどの位置 (バイト数や文字数ではなく、書記素単位) から探し始めるのかを指定します。 負のオフセットは、文字列の末尾からのオフセットと解釈されます。 `offset` の値にかかわらず、返される値は常に `haystack` の先頭からの位置になります。

`locale`
  使用するロケール。

### 戻り値

位置を表す整数値を返します。`needle` が見つからない場合は grapheme_strpos() は `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | オプションのパラメータ `locale` が追加されました。
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_strripos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strripos — 大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける

### 説明

手続き型

function grapheme_strripos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
string `$locale` = ""
): int|false

大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つけます。

### パラメータ

`haystack`

  探す対象となる文字列。正しい形式の UTF-8 でなければなりません。

`needle`

  探したい文字列。正しい形式の UTF-8 でなければなりません。

`offset`

  オプションの `offset` パラメータで、`haystack` のどの位置 (バイト数や文字数ではなく、書記素単位) から探し始めるのかを指定します。 `offset` の値にかかわらず、返される値は常に `haystack` の先頭からの位置になります。

`locale`
  使用するロケール。

### 戻り値

位置を表す整数値を返します。`needle` が見つからない場合は grapheme_strripos() は `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | オプションのパラメータ `locale` が追加されました。

### 例

例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_strrpos

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strrpos — 文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける

### 説明

手続き型

function grapheme_strrpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
string `$locale` = ""
): int|false

文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つけます。

### パラメータ

`haystack`

  探す対象となる文字列。正しい形式の UTF-8 でなければなりません。

`needle`

  探したい文字列。正しい形式の UTF-8 でなければなりません。

`offset`

  オプションの `offset` パラメータで、`haystack` のどの位置 (バイト数や文字数ではなく、書記素単位) から探し始めるのかを指定します。 `offset` の値にかかわらず、返される値は常に `haystack` の先頭からの位置になります。

`locale`
  使用するロケール。

### 戻り値

位置を表す整数値を返します。`needle` が見つからない場合は grapheme_strrpos() は `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | オプションのパラメータ `locale` が追加されました。

### 例

例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

# grapheme_strstr

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_strstr — haystack 文字列の中で、needle が最初に登場した場所以降の部分文字列を返す

### 説明

手続き型

function grapheme_strstr(
string `$haystack`,
string `$needle`,
bool `$beforeNeedle` = `false`,
string `$locale` = ""
): string|false

haystack 文字列の中で needle が最初に登場した場所を含めてそれ以降の部分文字列を返します。

### パラメータ

`haystack`

  入力文字列。正しい形式の UTF-8 でなければなりません。

`needle`

  探したい文字列。正しい形式の UTF-8 でなければなりません。

`beforeNeedle`

  `true` の場合、grapheme_strstr() は `needle` が最初に登場した場所より前の `haystack` の部分文字列を返します (`needle` は含めません)。

`locale`
  使用するロケール。

### 戻り値

`haystack` の部分文字列、あるいは `needle` が見つからなかった場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | オプションのパラメータ `locale` が追加されました。

### 例

例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_substr

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

grapheme_substr — 部分文字列を返す

### 説明

手続き型

function grapheme_substr(
string `$string`,
int `$offset`,
?int `$length` = `null`,
string `$locale` = ""
): string|false

部分文字列を返します。

### パラメータ

`string`

  入力文字列。正しい形式の UTF-8 でなければなりません。

`offset`

  デフォルトの書記素単位での開始位置。 `offset` がゼロ以上である場合は、`string` の `offset` 番目の位置から始まる文字列を返します。位置はゼロから数え始めます。 `offset` が負の場合は、文字列の末尾から数えて `offset` 番目 (書記素単位) の位置以降の文字列を返します。

`length`

  長さを書記素単位で指定します。 `length` が正の値の場合は、`offset` から数えて最大 `length` 文字までの文字列を返します (文字列全体の長さによって変わります)。 `length` が負の値の場合は、文字列の末尾から多くの書記素が削除されます (`offset` が負の場合にはまず開始位置を算出してから行います)。 `offset` がこの削除された場所以降になる場合は、空文字列を返します。

`locale`
  使用するロケール。

### 戻り値

`string` の部分文字列を返します。 失敗した場合に `false` を返します

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | オプションのパラメータ `locale` が追加されました。
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

## 目次

- grapheme_extract — デフォルトの書記素クラスタシーケンスをテキストバッファから取り出す関数。 テキストは UTF-8 でエンコードされている必要があります
- grapheme_str_split — 書記素クラスターを受け取り、文字の配列を返す
- grapheme_stripos — 大文字小文字を区別せず、文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
- grapheme_stristr — 大文字小文字を区別せず、haystack 文字列の中で needle が最初に登場した場所以降の部分文字列を返す
- grapheme_strlen — 書記素単位で文字列の長さを取得する
- grapheme_strpos — 文字列内で最初にあらわれる場所の (書記素単位の) 位置を見つける
- grapheme_strripos — 大文字小文字を区別せず、文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
- grapheme_strrpos — 文字列内で最後にあらわれる場所の (書記素単位の) 位置を見つける
- grapheme_strstr — haystack 文字列の中で、needle が最初に登場した場所以降の部分文字列を返す
- grapheme_substr — 部分文字列を返す

# IDN 関数

# 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形式に変換する

### 説明

手続き型

function 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` を返します

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `domain` パラメータが空の場合、 ValueError をスローするようになりました。
8.4.0 | `variant` パラメータが `INTL_IDNA_VARIANT_UTS46` でない場合、 ValueError をスローするようになりました。
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('täst.de');

    ?>

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

    xn--tst-qla.de

例2 全てASCIIで構成されたドメイン名は、小文字に変換される

    <?php

    var_dump(idn_to_ascii('Example.com'));

    ?>

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

    string(11) "example.com"

### 参考

- idn_to_utf8() - 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に変換する

### 説明

手続き型

function 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` を返します

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `domain` パラメータが空の場合、 ValueError をスローするようになりました。
8.4.0 | `variant` パラメータが `INTL_IDNA_VARIANT_UTS46` でない場合、 ValueError をスローするようになりました。
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形式に変換する

## 目次

- idn_to_ascii — ドメイン名をIDNAのASCII形式に変換する
- idn_to_utf8 — IDNAのASCII方式でエンコードされたドメイン名をUnicodeに変換する

# 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_IDS_UNARY_OPERATOR;
public const int PROPERTY_ID_COMPAT_MATH_START;
public const int PROPERTY_ID_COMPAT_MATH_CONTINUE;
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 function charAge(int|string `$codepoint`): ?array
public static function charDigitValue(int|string `$codepoint`): ?int
public static function charDirection(int|string `$codepoint`): ?int
public static function charFromName(string `$name`, int `$type` = `IntlChar::UNICODE_CHAR_NAME`): ?int
public static function charMirror(int|string `$codepoint`): int|string|null
public static function charName(int|string `$codepoint`, int `$type` = `IntlChar::UNICODE_CHAR_NAME`): ?string
public static function charType(int|string `$codepoint`): ?int
public static function chr(int|string `$codepoint`): ?string
public static function digit(int|string `$codepoint`, int `$base` = 10): int|false|null
public static function enumCharNames(
int|string `$start`,
int|string `$end`,
callable `$callback`,
int `$type` = `IntlChar::UNICODE_CHAR_NAME`
): bool
public static function enumCharTypes(callable `$callback`): void
public static function foldCase(int|string `$codepoint`, int `$options` = `IntlChar::FOLD_CASE_DEFAULT`): int|string|null
public static function forDigit(int `$digit`, int `$base` = 10): int
public static function getBidiPairedBracket(int|string `$codepoint`): int|string|null
public static function getBlockCode(int|string `$codepoint`): ?int
public static function getCombiningClass(int|string `$codepoint`): ?int
public static function getFC_NFKC_Closure(int|string `$codepoint`): string|false|null
public static function getIntPropertyMaxValue(int `$property`): int
public static function getIntPropertyMinValue(int `$property`): int
public static function getIntPropertyValue(int|string `$codepoint`, int `$property`): ?int
public static function getNumericValue(int|string `$codepoint`): ?float
public static function getPropertyEnum(string `$alias`): int
public static function getPropertyName(int `$property`, int `$type` = `IntlChar::LONG_PROPERTY_NAME`): string|false
public static function getPropertyValueEnum(int `$property`, string `$name`): int
public static function getPropertyValueName(int `$property`, int `$value`, int `$type` = `IntlChar::LONG_PROPERTY_NAME`): string|false
public static function getUnicodeVersion(): array
public static function hasBinaryProperty(int|string `$codepoint`, int `$property`): ?bool
public static function isalnum(int|string `$codepoint`): ?bool
public static function isalpha(int|string `$codepoint`): ?bool
public static function isbase(int|string `$codepoint`): ?bool
public static function isblank(int|string `$codepoint`): ?bool
public static function iscntrl(int|string `$codepoint`): ?bool
public static function isdefined(int|string `$codepoint`): ?bool
public static function isdigit(int|string `$codepoint`): ?bool
public static function isgraph(int|string `$codepoint`): ?bool
public static function isIDIgnorable(int|string `$codepoint`): ?bool
public static function isIDPart(int|string `$codepoint`): ?bool
public static function isIDStart(int|string `$codepoint`): ?bool
public static function isISOControl(int|string `$codepoint`): ?bool
public static function isJavaIDPart(int|string `$codepoint`): ?bool
public static function isJavaIDStart(int|string `$codepoint`): ?bool
public static function isJavaSpaceChar(int|string `$codepoint`): ?bool
public static function islower(int|string `$codepoint`): ?bool
public static function isMirrored(int|string `$codepoint`): ?bool
public static function isprint(int|string `$codepoint`): ?bool
public static function ispunct(int|string `$codepoint`): ?bool
public static function isspace(int|string `$codepoint`): ?bool
public static function istitle(int|string `$codepoint`): ?bool
public static function isUAlphabetic(int|string `$codepoint`): ?bool
public static function isULowercase(int|string `$codepoint`): ?bool
public static function isupper(int|string `$codepoint`): ?bool
public static function isUUppercase(int|string `$codepoint`): ?bool
public static function isUWhiteSpace(int|string `$codepoint`): ?bool
public static function isWhitespace(int|string `$codepoint`): ?bool
public static function isxdigit(int|string `$codepoint`): ?bool
public static function ord(int|string `$character`): ?int
public static function tolower(int|string `$codepoint`): int|string|null
public static function totitle(int|string `$codepoint`): int|string|null
public static function toupper(int|string `$codepoint`): int|string|null
}

## 定義済み定数

`IntlChar::UNICODE_VERSION` string

`IntlChar::CODEPOINT_MIN` int

`IntlChar::CODEPOINT_MAX` int

`IntlChar::NO_NUMERIC_VALUE` int

  Special value that is returned by IntlChar::getNumericValue() when no numeric value is defined for a code point.

`IntlChar::PROPERTY_ALPHABETIC` int

`IntlChar::PROPERTY_BINARY_START` int

`IntlChar::PROPERTY_ASCII_HEX_DIGIT` int

`IntlChar::PROPERTY_BIDI_CONTROL` int

`IntlChar::PROPERTY_BIDI_MIRRORED` int

`IntlChar::PROPERTY_DASH` int

`IntlChar::PROPERTY_DEFAULT_IGNORABLE_CODE_POINT` int

`IntlChar::PROPERTY_DEPRECATED` int

`IntlChar::PROPERTY_DIACRITIC` int

`IntlChar::PROPERTY_EXTENDER` int

`IntlChar::PROPERTY_FULL_COMPOSITION_EXCLUSION` int

`IntlChar::PROPERTY_GRAPHEME_BASE` int

`IntlChar::PROPERTY_GRAPHEME_EXTEND` int

`IntlChar::PROPERTY_GRAPHEME_LINK` int

`IntlChar::PROPERTY_HEX_DIGIT` int

`IntlChar::PROPERTY_HYPHEN` int

`IntlChar::PROPERTY_ID_CONTINUE` int

`IntlChar::PROPERTY_ID_START` int

`IntlChar::PROPERTY_IDEOGRAPHIC` int

`IntlChar::PROPERTY_IDS_BINARY_OPERATOR` int

`IntlChar::PROPERTY_IDS_TRINARY_OPERATOR` int

`IntlChar::PROPERTY_IDS_UNARY_OPERATOR` int
  Ideographic Description Sequences をプログラム的に決定するために使います。PHP 8.4.0 以降で利用可能です。
`IntlChar::PROPERTY_ID_COMPAT_MATH_START` int
  UAX 31 の mathematical identifier profile で使います。PHP 8.4.0 以降で利用可能です。
`IntlChar::PROPERTY_ID_COMPAT_MATH_CONTINUE` int
  UAX 31 の mathematical identifier profile で使います。PHP 8.4.0 以降で利用可能です。
`IntlChar::PROPERTY_JOIN_CONTROL` int

`IntlChar::PROPERTY_LOGICAL_ORDER_EXCEPTION` int

`IntlChar::PROPERTY_LOWERCASE` int

`IntlChar::PROPERTY_MATH` int

`IntlChar::PROPERTY_NONCHARACTER_CODE_POINT` int

`IntlChar::PROPERTY_QUOTATION_MARK` int

`IntlChar::PROPERTY_RADICAL` int

`IntlChar::PROPERTY_SOFT_DOTTED` int

`IntlChar::PROPERTY_TERMINAL_PUNCTUATION` int

`IntlChar::PROPERTY_UNIFIED_IDEOGRAPH` int

`IntlChar::PROPERTY_UPPERCASE` int

`IntlChar::PROPERTY_WHITE_SPACE` int

`IntlChar::PROPERTY_XID_CONTINUE` int

`IntlChar::PROPERTY_XID_START` int

`IntlChar::PROPERTY_CASE_SENSITIVE` int

`IntlChar::PROPERTY_S_TERM` int

`IntlChar::PROPERTY_VARIATION_SELECTOR` int

`IntlChar::PROPERTY_NFD_INERT` int

`IntlChar::PROPERTY_NFKD_INERT` int

`IntlChar::PROPERTY_NFC_INERT` int

`IntlChar::PROPERTY_NFKC_INERT` int

`IntlChar::PROPERTY_SEGMENT_STARTER` int

`IntlChar::PROPERTY_PATTERN_SYNTAX` int

`IntlChar::PROPERTY_PATTERN_WHITE_SPACE` int

`IntlChar::PROPERTY_POSIX_ALNUM` int

`IntlChar::PROPERTY_POSIX_BLANK` int

`IntlChar::PROPERTY_POSIX_GRAPH` int

`IntlChar::PROPERTY_POSIX_PRINT` int

`IntlChar::PROPERTY_POSIX_XDIGIT` int

`IntlChar::PROPERTY_CASED` int

`IntlChar::PROPERTY_CASE_IGNORABLE` int

`IntlChar::PROPERTY_CHANGES_WHEN_LOWERCASED` int

`IntlChar::PROPERTY_CHANGES_WHEN_UPPERCASED` int

`IntlChar::PROPERTY_CHANGES_WHEN_TITLECASED` int

`IntlChar::PROPERTY_CHANGES_WHEN_CASEFOLDED` int

`IntlChar::PROPERTY_CHANGES_WHEN_CASEMAPPED` int

`IntlChar::PROPERTY_CHANGES_WHEN_NFKC_CASEFOLDED` int

`IntlChar::PROPERTY_BINARY_LIMIT` int

`IntlChar::PROPERTY_BIDI_CLASS` int

`IntlChar::PROPERTY_INT_START` int

`IntlChar::PROPERTY_BLOCK` int

`IntlChar::PROPERTY_CANONICAL_COMBINING_CLASS` int

`IntlChar::PROPERTY_DECOMPOSITION_TYPE` int

`IntlChar::PROPERTY_EAST_ASIAN_WIDTH` int

`IntlChar::PROPERTY_GENERAL_CATEGORY` int

`IntlChar::PROPERTY_JOINING_GROUP` int

`IntlChar::PROPERTY_JOINING_TYPE` int

`IntlChar::PROPERTY_LINE_BREAK` int

`IntlChar::PROPERTY_NUMERIC_TYPE` int

`IntlChar::PROPERTY_SCRIPT` int

`IntlChar::PROPERTY_HANGUL_SYLLABLE_TYPE` int

`IntlChar::PROPERTY_NFD_QUICK_CHECK` int

`IntlChar::PROPERTY_NFKD_QUICK_CHECK` int

`IntlChar::PROPERTY_NFC_QUICK_CHECK` int

`IntlChar::PROPERTY_NFKC_QUICK_CHECK` int

`IntlChar::PROPERTY_LEAD_CANONICAL_COMBINING_CLASS` int

`IntlChar::PROPERTY_TRAIL_CANONICAL_COMBINING_CLASS` int

`IntlChar::PROPERTY_GRAPHEME_CLUSTER_BREAK` int

`IntlChar::PROPERTY_SENTENCE_BREAK` int

`IntlChar::PROPERTY_WORD_BREAK` int

`IntlChar::PROPERTY_BIDI_PAIRED_BRACKET_TYPE` int

`IntlChar::PROPERTY_INT_LIMIT` int

`IntlChar::PROPERTY_GENERAL_CATEGORY_MASK` int

`IntlChar::PROPERTY_MASK_START` int

`IntlChar::PROPERTY_MASK_LIMIT` int

`IntlChar::PROPERTY_NUMERIC_VALUE` int

`IntlChar::PROPERTY_DOUBLE_START` int

`IntlChar::PROPERTY_DOUBLE_LIMIT` int

`IntlChar::PROPERTY_AGE` int

`IntlChar::PROPERTY_STRING_START` int

`IntlChar::PROPERTY_BIDI_MIRRORING_GLYPH` int

`IntlChar::PROPERTY_CASE_FOLDING` int

`IntlChar::PROPERTY_ISO_COMMENT` int

`IntlChar::PROPERTY_LOWERCASE_MAPPING` int

`IntlChar::PROPERTY_NAME` int

`IntlChar::PROPERTY_SIMPLE_CASE_FOLDING` int

`IntlChar::PROPERTY_SIMPLE_LOWERCASE_MAPPING` int

`IntlChar::PROPERTY_SIMPLE_TITLECASE_MAPPING` int

`IntlChar::PROPERTY_SIMPLE_UPPERCASE_MAPPING` int

`IntlChar::PROPERTY_TITLECASE_MAPPING` int

`IntlChar::PROPERTY_UNICODE_1_NAME` int

`IntlChar::PROPERTY_UPPERCASE_MAPPING` int

`IntlChar::PROPERTY_BIDI_PAIRED_BRACKET` int

`IntlChar::PROPERTY_STRING_LIMIT` int

`IntlChar::PROPERTY_SCRIPT_EXTENSIONS` int

`IntlChar::PROPERTY_OTHER_PROPERTY_START` int

`IntlChar::PROPERTY_OTHER_PROPERTY_LIMIT` int

`IntlChar::PROPERTY_INVALID_CODE` int

`IntlChar::CHAR_CATEGORY_UNASSIGNED` int

`IntlChar::CHAR_CATEGORY_GENERAL_OTHER_TYPES` int

`IntlChar::CHAR_CATEGORY_UPPERCASE_LETTER` int

`IntlChar::CHAR_CATEGORY_LOWERCASE_LETTER` int

`IntlChar::CHAR_CATEGORY_TITLECASE_LETTER` int

`IntlChar::CHAR_CATEGORY_MODIFIER_LETTER` int

`IntlChar::CHAR_CATEGORY_OTHER_LETTER` int

`IntlChar::CHAR_CATEGORY_NON_SPACING_MARK` int

`IntlChar::CHAR_CATEGORY_ENCLOSING_MARK` int

`IntlChar::CHAR_CATEGORY_COMBINING_SPACING_MARK` int

`IntlChar::CHAR_CATEGORY_DECIMAL_DIGIT_NUMBER` int

`IntlChar::CHAR_CATEGORY_LETTER_NUMBER` int

`IntlChar::CHAR_CATEGORY_OTHER_NUMBER` int

`IntlChar::CHAR_CATEGORY_SPACE_SEPARATOR` int

`IntlChar::CHAR_CATEGORY_LINE_SEPARATOR` int

`IntlChar::CHAR_CATEGORY_PARAGRAPH_SEPARATOR` int

`IntlChar::CHAR_CATEGORY_CONTROL_CHAR` int

`IntlChar::CHAR_CATEGORY_FORMAT_CHAR` int

`IntlChar::CHAR_CATEGORY_PRIVATE_USE_CHAR` int

`IntlChar::CHAR_CATEGORY_SURROGATE` int

`IntlChar::CHAR_CATEGORY_DASH_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_START_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_END_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_CONNECTOR_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_OTHER_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_MATH_SYMBOL` int

`IntlChar::CHAR_CATEGORY_CURRENCY_SYMBOL` int

`IntlChar::CHAR_CATEGORY_MODIFIER_SYMBOL` int

`IntlChar::CHAR_CATEGORY_OTHER_SYMBOL` int

`IntlChar::CHAR_CATEGORY_INITIAL_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_FINAL_PUNCTUATION` int

`IntlChar::CHAR_CATEGORY_CHAR_CATEGORY_COUNT` int

`IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT` int

`IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER` int

`IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_SEPARATOR` int

`IntlChar::CHAR_DIRECTION_EUROPEAN_NUMBER_TERMINATOR` int

`IntlChar::CHAR_DIRECTION_ARABIC_NUMBER` int

`IntlChar::CHAR_DIRECTION_COMMON_NUMBER_SEPARATOR` int

`IntlChar::CHAR_DIRECTION_BLOCK_SEPARATOR` int

`IntlChar::CHAR_DIRECTION_SEGMENT_SEPARATOR` int

`IntlChar::CHAR_DIRECTION_WHITE_SPACE_NEUTRAL` int

`IntlChar::CHAR_DIRECTION_OTHER_NEUTRAL` int

`IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_EMBEDDING` int

`IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_OVERRIDE` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ARABIC` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_EMBEDDING` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_OVERRIDE` int

`IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_FORMAT` int

`IntlChar::CHAR_DIRECTION_DIR_NON_SPACING_MARK` int

`IntlChar::CHAR_DIRECTION_BOUNDARY_NEUTRAL` int

`IntlChar::CHAR_DIRECTION_FIRST_STRONG_ISOLATE` int

`IntlChar::CHAR_DIRECTION_LEFT_TO_RIGHT_ISOLATE` int

`IntlChar::CHAR_DIRECTION_RIGHT_TO_LEFT_ISOLATE` int

`IntlChar::CHAR_DIRECTION_POP_DIRECTIONAL_ISOLATE` int

`IntlChar::CHAR_DIRECTION_CHAR_DIRECTION_COUNT` int

`IntlChar::BLOCK_CODE_NO_BLOCK` int

`IntlChar::BLOCK_CODE_BASIC_LATIN` int

`IntlChar::BLOCK_CODE_LATIN_1_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_A` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_B` int

`IntlChar::BLOCK_CODE_IPA_EXTENSIONS` int

`IntlChar::BLOCK_CODE_SPACING_MODIFIER_LETTERS` int

`IntlChar::BLOCK_CODE_COMBINING_DIACRITICAL_MARKS` int

`IntlChar::BLOCK_CODE_GREEK` int

`IntlChar::BLOCK_CODE_CYRILLIC` int

`IntlChar::BLOCK_CODE_ARMENIAN` int

`IntlChar::BLOCK_CODE_HEBREW` int

`IntlChar::BLOCK_CODE_ARABIC` int

`IntlChar::BLOCK_CODE_SYRIAC` int

`IntlChar::BLOCK_CODE_THAANA` int

`IntlChar::BLOCK_CODE_DEVANAGARI` int

`IntlChar::BLOCK_CODE_BENGALI` int

`IntlChar::BLOCK_CODE_GURMUKHI` int

`IntlChar::BLOCK_CODE_GUJARATI` int

`IntlChar::BLOCK_CODE_ORIYA` int

`IntlChar::BLOCK_CODE_TAMIL` int

`IntlChar::BLOCK_CODE_TELUGU` int

`IntlChar::BLOCK_CODE_KANNADA` int

`IntlChar::BLOCK_CODE_MALAYALAM` int

`IntlChar::BLOCK_CODE_SINHALA` int

`IntlChar::BLOCK_CODE_THAI` int

`IntlChar::BLOCK_CODE_LAO` int

`IntlChar::BLOCK_CODE_TIBETAN` int

`IntlChar::BLOCK_CODE_MYANMAR` int

`IntlChar::BLOCK_CODE_GEORGIAN` int

`IntlChar::BLOCK_CODE_HANGUL_JAMO` int

`IntlChar::BLOCK_CODE_ETHIOPIC` int

`IntlChar::BLOCK_CODE_CHEROKEE` int

`IntlChar::BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS` int

`IntlChar::BLOCK_CODE_OGHAM` int

`IntlChar::BLOCK_CODE_RUNIC` int

`IntlChar::BLOCK_CODE_KHMER` int

`IntlChar::BLOCK_CODE_MONGOLIAN` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_ADDITIONAL` int

`IntlChar::BLOCK_CODE_GREEK_EXTENDED` int

`IntlChar::BLOCK_CODE_GENERAL_PUNCTUATION` int

`IntlChar::BLOCK_CODE_SUPERSCRIPTS_AND_SUBSCRIPTS` int

`IntlChar::BLOCK_CODE_CURRENCY_SYMBOLS` int

`IntlChar::BLOCK_CODE_COMBINING_MARKS_FOR_SYMBOLS` int

`IntlChar::BLOCK_CODE_LETTERLIKE_SYMBOLS` int

`IntlChar::BLOCK_CODE_NUMBER_FORMS` int

`IntlChar::BLOCK_CODE_ARROWS` int

`IntlChar::BLOCK_CODE_MATHEMATICAL_OPERATORS` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_TECHNICAL` int

`IntlChar::BLOCK_CODE_CONTROL_PICTURES` int

`IntlChar::BLOCK_CODE_OPTICAL_CHARACTER_RECOGNITION` int

`IntlChar::BLOCK_CODE_ENCLOSED_ALPHANUMERICS` int

`IntlChar::BLOCK_CODE_BOX_DRAWING` int

`IntlChar::BLOCK_CODE_BLOCK_ELEMENTS` int

`IntlChar::BLOCK_CODE_GEOMETRIC_SHAPES` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS` int

`IntlChar::BLOCK_CODE_DINGBATS` int

`IntlChar::BLOCK_CODE_BRAILLE_PATTERNS` int

`IntlChar::BLOCK_CODE_CJK_RADICALS_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_KANGXI_RADICALS` int

`IntlChar::BLOCK_CODE_IDEOGRAPHIC_DESCRIPTION_CHARACTERS` int

`IntlChar::BLOCK_CODE_CJK_SYMBOLS_AND_PUNCTUATION` int

`IntlChar::BLOCK_CODE_HIRAGANA` int

`IntlChar::BLOCK_CODE_KATAKANA` int

`IntlChar::BLOCK_CODE_BOPOMOFO` int

`IntlChar::BLOCK_CODE_HANGUL_COMPATIBILITY_JAMO` int

`IntlChar::BLOCK_CODE_KANBUN` int

`IntlChar::BLOCK_CODE_BOPOMOFO_EXTENDED` int

`IntlChar::BLOCK_CODE_ENCLOSED_CJK_LETTERS_AND_MONTHS` int

`IntlChar::BLOCK_CODE_CJK_COMPATIBILITY` int

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_A` int

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS` int

`IntlChar::BLOCK_CODE_YI_SYLLABLES` int

`IntlChar::BLOCK_CODE_YI_RADICALS` int

`IntlChar::BLOCK_CODE_HANGUL_SYLLABLES` int

`IntlChar::BLOCK_CODE_HIGH_SURROGATES` int

`IntlChar::BLOCK_CODE_HIGH_PRIVATE_USE_SURROGATES` int

`IntlChar::BLOCK_CODE_LOW_SURROGATES` int

`IntlChar::BLOCK_CODE_PRIVATE_USE_AREA` int

`IntlChar::BLOCK_CODE_PRIVATE_USE` int

`IntlChar::BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS` int

`IntlChar::BLOCK_CODE_ALPHABETIC_PRESENTATION_FORMS` int

`IntlChar::BLOCK_CODE_ARABIC_PRESENTATION_FORMS_A` int

`IntlChar::BLOCK_CODE_COMBINING_HALF_MARKS` int

`IntlChar::BLOCK_CODE_CJK_COMPATIBILITY_FORMS` int

`IntlChar::BLOCK_CODE_SMALL_FORM_VARIANTS` int

`IntlChar::BLOCK_CODE_ARABIC_PRESENTATION_FORMS_B` int

`IntlChar::BLOCK_CODE_SPECIALS` int

`IntlChar::BLOCK_CODE_HALFWIDTH_AND_FULLWIDTH_FORMS` int

`IntlChar::BLOCK_CODE_OLD_ITALIC` int

`IntlChar::BLOCK_CODE_GOTHIC` int

`IntlChar::BLOCK_CODE_DESERET` int

`IntlChar::BLOCK_CODE_BYZANTINE_MUSICAL_SYMBOLS` int

`IntlChar::BLOCK_CODE_MUSICAL_SYMBOLS` int

`IntlChar::BLOCK_CODE_MATHEMATICAL_ALPHANUMERIC_SYMBOLS` int

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_B` int

`IntlChar::BLOCK_CODE_CJK_COMPATIBILITY_IDEOGRAPHS_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_TAGS` int

`IntlChar::BLOCK_CODE_CYRILLIC_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_CYRILLIC_SUPPLEMENTARY` int

`IntlChar::BLOCK_CODE_TAGALOG` int

`IntlChar::BLOCK_CODE_HANUNOO` int

`IntlChar::BLOCK_CODE_BUHID` int

`IntlChar::BLOCK_CODE_TAGBANWA` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_A` int

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_ARROWS_A` int

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_ARROWS_B` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_MATHEMATICAL_SYMBOLS_B` int

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_MATHEMATICAL_OPERATORS` int

`IntlChar::BLOCK_CODE_KATAKANA_PHONETIC_EXTENSIONS` int

`IntlChar::BLOCK_CODE_VARIATION_SELECTORS` int

`IntlChar::BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_A` int

`IntlChar::BLOCK_CODE_SUPPLEMENTARY_PRIVATE_USE_AREA_B` int

`IntlChar::BLOCK_CODE_LIMBU` int

`IntlChar::BLOCK_CODE_TAI_LE` int

`IntlChar::BLOCK_CODE_KHMER_SYMBOLS` int

`IntlChar::BLOCK_CODE_PHONETIC_EXTENSIONS` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_ARROWS` int

`IntlChar::BLOCK_CODE_YIJING_HEXAGRAM_SYMBOLS` int

`IntlChar::BLOCK_CODE_LINEAR_B_SYLLABARY` int

`IntlChar::BLOCK_CODE_LINEAR_B_IDEOGRAMS` int

`IntlChar::BLOCK_CODE_AEGEAN_NUMBERS` int

`IntlChar::BLOCK_CODE_UGARITIC` int

`IntlChar::BLOCK_CODE_SHAVIAN` int

`IntlChar::BLOCK_CODE_OSMANYA` int

`IntlChar::BLOCK_CODE_CYPRIOT_SYLLABARY` int

`IntlChar::BLOCK_CODE_TAI_XUAN_JING_SYMBOLS` int

`IntlChar::BLOCK_CODE_VARIATION_SELECTORS_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_ANCIENT_GREEK_MUSICAL_NOTATION` int

`IntlChar::BLOCK_CODE_ANCIENT_GREEK_NUMBERS` int

`IntlChar::BLOCK_CODE_ARABIC_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_BUGINESE` int

`IntlChar::BLOCK_CODE_CJK_STROKES` int

`IntlChar::BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_COPTIC` int

`IntlChar::BLOCK_CODE_ETHIOPIC_EXTENDED` int

`IntlChar::BLOCK_CODE_ETHIOPIC_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_GEORGIAN_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_GLAGOLITIC` int

`IntlChar::BLOCK_CODE_KHAROSHTHI` int

`IntlChar::BLOCK_CODE_MODIFIER_TONE_LETTERS` int

`IntlChar::BLOCK_CODE_NEW_TAI_LUE` int

`IntlChar::BLOCK_CODE_OLD_PERSIAN` int

`IntlChar::BLOCK_CODE_PHONETIC_EXTENSIONS_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_PUNCTUATION` int

`IntlChar::BLOCK_CODE_SYLOTI_NAGRI` int

`IntlChar::BLOCK_CODE_TIFINAGH` int

`IntlChar::BLOCK_CODE_VERTICAL_FORMS` int

`IntlChar::BLOCK_CODE_NKO` int

`IntlChar::BLOCK_CODE_BALINESE` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_C` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_D` int

`IntlChar::BLOCK_CODE_PHAGS_PA` int

`IntlChar::BLOCK_CODE_PHOENICIAN` int

`IntlChar::BLOCK_CODE_CUNEIFORM` int

`IntlChar::BLOCK_CODE_CUNEIFORM_NUMBERS_AND_PUNCTUATION` int

`IntlChar::BLOCK_CODE_COUNTING_ROD_NUMERALS` int

`IntlChar::BLOCK_CODE_SUNDANESE` int

`IntlChar::BLOCK_CODE_LEPCHA` int

`IntlChar::BLOCK_CODE_OL_CHIKI` int

`IntlChar::BLOCK_CODE_CYRILLIC_EXTENDED_A` int

`IntlChar::BLOCK_CODE_VAI` int

`IntlChar::BLOCK_CODE_CYRILLIC_EXTENDED_B` int

`IntlChar::BLOCK_CODE_SAURASHTRA` int

`IntlChar::BLOCK_CODE_KAYAH_LI` int

`IntlChar::BLOCK_CODE_REJANG` int

`IntlChar::BLOCK_CODE_CHAM` int

`IntlChar::BLOCK_CODE_ANCIENT_SYMBOLS` int

`IntlChar::BLOCK_CODE_PHAISTOS_DISC` int

`IntlChar::BLOCK_CODE_LYCIAN` int

`IntlChar::BLOCK_CODE_CARIAN` int

`IntlChar::BLOCK_CODE_LYDIAN` int

`IntlChar::BLOCK_CODE_MAHJONG_TILES` int

`IntlChar::BLOCK_CODE_DOMINO_TILES` int

`IntlChar::BLOCK_CODE_SAMARITAN` int

`IntlChar::BLOCK_CODE_UNIFIED_CANADIAN_ABORIGINAL_SYLLABICS_EXTENDED` int

`IntlChar::BLOCK_CODE_TAI_THAM` int

`IntlChar::BLOCK_CODE_VEDIC_EXTENSIONS` int

`IntlChar::BLOCK_CODE_LISU` int

`IntlChar::BLOCK_CODE_BAMUM` int

`IntlChar::BLOCK_CODE_COMMON_INDIC_NUMBER_FORMS` int

`IntlChar::BLOCK_CODE_DEVANAGARI_EXTENDED` int

`IntlChar::BLOCK_CODE_HANGUL_JAMO_EXTENDED_A` int

`IntlChar::BLOCK_CODE_JAVANESE` int

`IntlChar::BLOCK_CODE_MYANMAR_EXTENDED_A` int

`IntlChar::BLOCK_CODE_TAI_VIET` int

`IntlChar::BLOCK_CODE_MEETEI_MAYEK` int

`IntlChar::BLOCK_CODE_HANGUL_JAMO_EXTENDED_B` int

`IntlChar::BLOCK_CODE_IMPERIAL_ARAMAIC` int

`IntlChar::BLOCK_CODE_OLD_SOUTH_ARABIAN` int

`IntlChar::BLOCK_CODE_AVESTAN` int

`IntlChar::BLOCK_CODE_INSCRIPTIONAL_PARTHIAN` int

`IntlChar::BLOCK_CODE_INSCRIPTIONAL_PAHLAVI` int

`IntlChar::BLOCK_CODE_OLD_TURKIC` int

`IntlChar::BLOCK_CODE_RUMI_NUMERAL_SYMBOLS` int

`IntlChar::BLOCK_CODE_KAITHI` int

`IntlChar::BLOCK_CODE_EGYPTIAN_HIEROGLYPHS` int

`IntlChar::BLOCK_CODE_ENCLOSED_ALPHANUMERIC_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_ENCLOSED_IDEOGRAPHIC_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_C` int

`IntlChar::BLOCK_CODE_MANDAIC` int

`IntlChar::BLOCK_CODE_BATAK` int

`IntlChar::BLOCK_CODE_ETHIOPIC_EXTENDED_A` int

`IntlChar::BLOCK_CODE_BRAHMI` int

`IntlChar::BLOCK_CODE_BAMUM_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_KANA_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_PLAYING_CARDS` int

`IntlChar::BLOCK_CODE_MISCELLANEOUS_SYMBOLS_AND_PICTOGRAPHS` int

`IntlChar::BLOCK_CODE_EMOTICONS` int

`IntlChar::BLOCK_CODE_TRANSPORT_AND_MAP_SYMBOLS` int

`IntlChar::BLOCK_CODE_ALCHEMICAL_SYMBOLS` int

`IntlChar::BLOCK_CODE_CJK_UNIFIED_IDEOGRAPHS_EXTENSION_D` int

`IntlChar::BLOCK_CODE_ARABIC_EXTENDED_A` int

`IntlChar::BLOCK_CODE_ARABIC_MATHEMATICAL_ALPHABETIC_SYMBOLS` int

`IntlChar::BLOCK_CODE_CHAKMA` int

`IntlChar::BLOCK_CODE_MEETEI_MAYEK_EXTENSIONS` int

`IntlChar::BLOCK_CODE_MEROITIC_CURSIVE` int

`IntlChar::BLOCK_CODE_MEROITIC_HIEROGLYPHS` int

`IntlChar::BLOCK_CODE_MIAO` int

`IntlChar::BLOCK_CODE_SHARADA` int

`IntlChar::BLOCK_CODE_SORA_SOMPENG` int

`IntlChar::BLOCK_CODE_SUNDANESE_SUPPLEMENT` int

`IntlChar::BLOCK_CODE_TAKRI` int

`IntlChar::BLOCK_CODE_BASSA_VAH` int

`IntlChar::BLOCK_CODE_CAUCASIAN_ALBANIAN` int

`IntlChar::BLOCK_CODE_COPTIC_EPACT_NUMBERS` int

`IntlChar::BLOCK_CODE_COMBINING_DIACRITICAL_MARKS_EXTENDED` int

`IntlChar::BLOCK_CODE_DUPLOYAN` int

`IntlChar::BLOCK_CODE_ELBASAN` int

`IntlChar::BLOCK_CODE_GEOMETRIC_SHAPES_EXTENDED` int

`IntlChar::BLOCK_CODE_GRANTHA` int

`IntlChar::BLOCK_CODE_KHOJKI` int

`IntlChar::BLOCK_CODE_KHUDAWADI` int

`IntlChar::BLOCK_CODE_LATIN_EXTENDED_E` int

`IntlChar::BLOCK_CODE_LINEAR_A` int

`IntlChar::BLOCK_CODE_MAHAJANI` int

`IntlChar::BLOCK_CODE_MANICHAEAN` int

`IntlChar::BLOCK_CODE_MENDE_KIKAKUI` int

`IntlChar::BLOCK_CODE_MODI` int

`IntlChar::BLOCK_CODE_MRO` int

`IntlChar::BLOCK_CODE_MYANMAR_EXTENDED_B` int

`IntlChar::BLOCK_CODE_NABATAEAN` int

`IntlChar::BLOCK_CODE_OLD_NORTH_ARABIAN` int

`IntlChar::BLOCK_CODE_OLD_PERMIC` int

`IntlChar::BLOCK_CODE_ORNAMENTAL_DINGBATS` int

`IntlChar::BLOCK_CODE_PAHAWH_HMONG` int

`IntlChar::BLOCK_CODE_PALMYRENE` int

`IntlChar::BLOCK_CODE_PAU_CIN_HAU` int

`IntlChar::BLOCK_CODE_PSALTER_PAHLAVI` int

`IntlChar::BLOCK_CODE_SHORTHAND_FORMAT_CONTROLS` int

`IntlChar::BLOCK_CODE_SIDDHAM` int

`IntlChar::BLOCK_CODE_SINHALA_ARCHAIC_NUMBERS` int

`IntlChar::BLOCK_CODE_SUPPLEMENTAL_ARROWS_C` int

`IntlChar::BLOCK_CODE_TIRHUTA` int

`IntlChar::BLOCK_CODE_WARANG_CITI` int

`IntlChar::BLOCK_CODE_COUNT` int

`IntlChar::BLOCK_CODE_INVALID_CODE` int

`IntlChar::BPT_NONE` int

`IntlChar::BPT_OPEN` int

`IntlChar::BPT_CLOSE` int

`IntlChar::BPT_COUNT` int

`IntlChar::EA_NEUTRAL` int

`IntlChar::EA_AMBIGUOUS` int

`IntlChar::EA_HALFWIDTH` int

`IntlChar::EA_FULLWIDTH` int

`IntlChar::EA_NARROW` int

`IntlChar::EA_WIDE` int

`IntlChar::EA_COUNT` int

`IntlChar::UNICODE_CHAR_NAME` int

`IntlChar::UNICODE_10_CHAR_NAME` int

`IntlChar::EXTENDED_CHAR_NAME` int

`IntlChar::CHAR_NAME_ALIAS` int

`IntlChar::CHAR_NAME_CHOICE_COUNT` int

`IntlChar::SHORT_PROPERTY_NAME` int

`IntlChar::LONG_PROPERTY_NAME` int

`IntlChar::PROPERTY_NAME_CHOICE_COUNT` int

`IntlChar::DT_NONE` int

`IntlChar::DT_CANONICAL` int

`IntlChar::DT_COMPAT` int

`IntlChar::DT_CIRCLE` int

`IntlChar::DT_FINAL` int

`IntlChar::DT_FONT` int

`IntlChar::DT_FRACTION` int

`IntlChar::DT_INITIAL` int

`IntlChar::DT_ISOLATED` int

`IntlChar::DT_MEDIAL` int

`IntlChar::DT_NARROW` int

`IntlChar::DT_NOBREAK` int

`IntlChar::DT_SMALL` int

`IntlChar::DT_SQUARE` int

`IntlChar::DT_SUB` int

`IntlChar::DT_SUPER` int

`IntlChar::DT_VERTICAL` int

`IntlChar::DT_WIDE` int

`IntlChar::DT_COUNT` int

`IntlChar::JT_NON_JOINING` int

`IntlChar::JT_JOIN_CAUSING` int

`IntlChar::JT_DUAL_JOINING` int

`IntlChar::JT_LEFT_JOINING` int

`IntlChar::JT_RIGHT_JOINING` int

`IntlChar::JT_TRANSPARENT` int

`IntlChar::JT_COUNT` int

`IntlChar::JG_NO_JOINING_GROUP` int

`IntlChar::JG_AIN` int

`IntlChar::JG_ALAPH` int

`IntlChar::JG_ALEF` int

`IntlChar::JG_BEH` int

`IntlChar::JG_BETH` int

`IntlChar::JG_DAL` int

`IntlChar::JG_DALATH_RISH` int

`IntlChar::JG_E` int

`IntlChar::JG_FEH` int

`IntlChar::JG_FINAL_SEMKATH` int

`IntlChar::JG_GAF` int

`IntlChar::JG_GAMAL` int

`IntlChar::JG_HAH` int

`IntlChar::JG_TEH_MARBUTA_GOAL` int

`IntlChar::JG_HAMZA_ON_HEH_GOAL` int

`IntlChar::JG_HE` int

`IntlChar::JG_HEH` int

`IntlChar::JG_HEH_GOAL` int

`IntlChar::JG_HETH` int

`IntlChar::JG_KAF` int

`IntlChar::JG_KAPH` int

`IntlChar::JG_KNOTTED_HEH` int

`IntlChar::JG_LAM` int

`IntlChar::JG_LAMADH` int

`IntlChar::JG_MEEM` int

`IntlChar::JG_MIM` int

`IntlChar::JG_NOON` int

`IntlChar::JG_NUN` int

`IntlChar::JG_PE` int

`IntlChar::JG_QAF` int

`IntlChar::JG_QAPH` int

`IntlChar::JG_REH` int

`IntlChar::JG_REVERSED_PE` int

`IntlChar::JG_SAD` int

`IntlChar::JG_SADHE` int

`IntlChar::JG_SEEN` int

`IntlChar::JG_SEMKATH` int

`IntlChar::JG_SHIN` int

`IntlChar::JG_SWASH_KAF` int

`IntlChar::JG_SYRIAC_WAW` int

`IntlChar::JG_TAH` int

`IntlChar::JG_TAW` int

`IntlChar::JG_TEH_MARBUTA` int

`IntlChar::JG_TETH` int

`IntlChar::JG_WAW` int

`IntlChar::JG_YEH` int

`IntlChar::JG_YEH_BARREE` int

`IntlChar::JG_YEH_WITH_TAIL` int

`IntlChar::JG_YUDH` int

`IntlChar::JG_YUDH_HE` int

`IntlChar::JG_ZAIN` int

`IntlChar::JG_FE` int

`IntlChar::JG_KHAPH` int

`IntlChar::JG_ZHAIN` int

`IntlChar::JG_BURUSHASKI_YEH_BARREE` int

`IntlChar::JG_FARSI_YEH` int

`IntlChar::JG_NYA` int

`IntlChar::JG_ROHINGYA_YEH` int

`IntlChar::JG_MANICHAEAN_ALEPH` int

`IntlChar::JG_MANICHAEAN_AYIN` int

`IntlChar::JG_MANICHAEAN_BETH` int

`IntlChar::JG_MANICHAEAN_DALETH` int

`IntlChar::JG_MANICHAEAN_DHAMEDH` int

`IntlChar::JG_MANICHAEAN_FIVE` int

`IntlChar::JG_MANICHAEAN_GIMEL` int

`IntlChar::JG_MANICHAEAN_HETH` int

`IntlChar::JG_MANICHAEAN_HUNDRED` int

`IntlChar::JG_MANICHAEAN_KAPH` int

`IntlChar::JG_MANICHAEAN_LAMEDH` int

`IntlChar::JG_MANICHAEAN_MEM` int

`IntlChar::JG_MANICHAEAN_NUN` int

`IntlChar::JG_MANICHAEAN_ONE` int

`IntlChar::JG_MANICHAEAN_PE` int

`IntlChar::JG_MANICHAEAN_QOPH` int

`IntlChar::JG_MANICHAEAN_RESH` int

`IntlChar::JG_MANICHAEAN_SADHE` int

`IntlChar::JG_MANICHAEAN_SAMEKH` int

`IntlChar::JG_MANICHAEAN_TAW` int

`IntlChar::JG_MANICHAEAN_TEN` int

`IntlChar::JG_MANICHAEAN_TETH` int

`IntlChar::JG_MANICHAEAN_THAMEDH` int

`IntlChar::JG_MANICHAEAN_TWENTY` int

`IntlChar::JG_MANICHAEAN_WAW` int

`IntlChar::JG_MANICHAEAN_YODH` int

`IntlChar::JG_MANICHAEAN_ZAYIN` int

`IntlChar::JG_STRAIGHT_WAW` int

`IntlChar::JG_COUNT` int

`IntlChar::GCB_OTHER` int

`IntlChar::GCB_CONTROL` int

`IntlChar::GCB_CR` int

`IntlChar::GCB_EXTEND` int

`IntlChar::GCB_L` int

`IntlChar::GCB_LF` int

`IntlChar::GCB_LV` int

`IntlChar::GCB_LVT` int

`IntlChar::GCB_T` int

`IntlChar::GCB_V` int

`IntlChar::GCB_SPACING_MARK` int

`IntlChar::GCB_PREPEND` int

`IntlChar::GCB_REGIONAL_INDICATOR` int

`IntlChar::GCB_COUNT` int

`IntlChar::WB_OTHER` int

`IntlChar::WB_ALETTER` int

`IntlChar::WB_FORMAT` int

`IntlChar::WB_KATAKANA` int

`IntlChar::WB_MIDLETTER` int

`IntlChar::WB_MIDNUM` int

`IntlChar::WB_NUMERIC` int

`IntlChar::WB_EXTENDNUMLET` int

`IntlChar::WB_CR` int

`IntlChar::WB_EXTEND` int

`IntlChar::WB_LF` int

`IntlChar::WB_MIDNUMLET` int

`IntlChar::WB_NEWLINE` int

`IntlChar::WB_REGIONAL_INDICATOR` int

`IntlChar::WB_HEBREW_LETTER` int

`IntlChar::WB_SINGLE_QUOTE` int

`IntlChar::WB_DOUBLE_QUOTE` int

`IntlChar::WB_COUNT` int

`IntlChar::SB_OTHER` int

`IntlChar::SB_ATERM` int

`IntlChar::SB_CLOSE` int

`IntlChar::SB_FORMAT` int

`IntlChar::SB_LOWER` int

`IntlChar::SB_NUMERIC` int

`IntlChar::SB_OLETTER` int

`IntlChar::SB_SEP` int

`IntlChar::SB_SP` int

`IntlChar::SB_STERM` int

`IntlChar::SB_UPPER` int

`IntlChar::SB_CR` int

`IntlChar::SB_EXTEND` int

`IntlChar::SB_LF` int

`IntlChar::SB_SCONTINUE` int

`IntlChar::SB_COUNT` int

`IntlChar::LB_UNKNOWN` int

`IntlChar::LB_AMBIGUOUS` int

`IntlChar::LB_ALPHABETIC` int

`IntlChar::LB_BREAK_BOTH` int

`IntlChar::LB_BREAK_AFTER` int

`IntlChar::LB_BREAK_BEFORE` int

`IntlChar::LB_MANDATORY_BREAK` int

`IntlChar::LB_CONTINGENT_BREAK` int

`IntlChar::LB_CLOSE_PUNCTUATION` int

`IntlChar::LB_COMBINING_MARK` int

`IntlChar::LB_CARRIAGE_RETURN` int

`IntlChar::LB_EXCLAMATION` int

`IntlChar::LB_GLUE` int

`IntlChar::LB_HYPHEN` int

`IntlChar::LB_IDEOGRAPHIC` int

`IntlChar::LB_INSEPARABLE` int

`IntlChar::LB_INSEPERABLE` int

`IntlChar::LB_INFIX_NUMERIC` int

`IntlChar::LB_LINE_FEED` int

`IntlChar::LB_NONSTARTER` int

`IntlChar::LB_NUMERIC` int

`IntlChar::LB_OPEN_PUNCTUATION` int

`IntlChar::LB_POSTFIX_NUMERIC` int

`IntlChar::LB_PREFIX_NUMERIC` int

`IntlChar::LB_QUOTATION` int

`IntlChar::LB_COMPLEX_CONTEXT` int

`IntlChar::LB_SURROGATE` int

`IntlChar::LB_SPACE` int

`IntlChar::LB_BREAK_SYMBOLS` int

`IntlChar::LB_ZWSPACE` int

`IntlChar::LB_NEXT_LINE` int

`IntlChar::LB_WORD_JOINER` int

`IntlChar::LB_H2` int

`IntlChar::LB_H3` int

`IntlChar::LB_JL` int

`IntlChar::LB_JT` int

`IntlChar::LB_JV` int

`IntlChar::LB_CLOSE_PARENTHESIS` int

`IntlChar::LB_CONDITIONAL_JAPANESE_STARTER` int

`IntlChar::LB_HEBREW_LETTER` int

`IntlChar::LB_REGIONAL_INDICATOR` int

`IntlChar::LB_COUNT` int

`IntlChar::NT_NONE` int

`IntlChar::NT_DECIMAL` int

`IntlChar::NT_DIGIT` int

`IntlChar::NT_NUMERIC` int

`IntlChar::NT_COUNT` int

`IntlChar::HST_NOT_APPLICABLE` int

`IntlChar::HST_LEADING_JAMO` int

`IntlChar::HST_VOWEL_JAMO` int

`IntlChar::HST_TRAILING_JAMO` int

`IntlChar::HST_LV_SYLLABLE` int

`IntlChar::HST_LVT_SYLLABLE` int

`IntlChar::HST_COUNT` int

`IntlChar::FOLD_CASE_DEFAULT` int

`IntlChar::FOLD_CASE_EXCLUDE_SPECIAL_I` int

## 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `IntlChar::PROPERTY_IDS_UNARY_OPERATOR`, `IntlChar::PROPERTY_ID_COMPAT_MATH_START`, `IntlChar::PROPERTY_ID_COMPAT_MATH_CONTINUE` が追加されました。
8.4.0 | クラス定数が型付けされました。
7.0.6 | The `IntlChar::NO_NUMERIC_VALUE` constant was added.

# IntlChar::charAge

(PHP 7, PHP 8)

IntlChar::charAge — コードポイントの "age" を取得する

### 説明

public static function 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 プロパティの値を取得する

# IntlChar::charDigitValue

(PHP 7, PHP 8)

IntlChar::charDigitValue — 10進数の桁の文字を桁の値として取得する

### 説明

public static function 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::charDirection

(PHP 7, PHP 8)

IntlChar::charDirection — コードポイントの双方向カテゴリの値を取得する

### 説明

public static function 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`

失敗した場合は、`null` を返します。

### 例

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

# IntlChar::charFromName

(PHP 7, PHP 8)

IntlChar::charFromName — 名前で Unicode 文字を探し、コードポイントの値を返す

### 説明

public static function 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::charMirror

(PHP 7, PHP 8)

IntlChar::charMirror — コードポイントの "鏡文字" を取得する

### 説明

public static function 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`

# IntlChar::charName

(PHP 7, PHP 8)

IntlChar::charName — Unicode 文字の名前を取得する

### 説明

public static function 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::charType

(PHP 7, PHP 8)

IntlChar::charType — コードポイントの一般カテゴリの値を取得する

### 説明

public static function 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)

# IntlChar::chr

(PHP 7, PHP 8)

IntlChar::chr — コードポイント値に対応する、Unicode 文字を返す

### 説明

public static function 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バイトの文字列を生成する

# IntlChar::digit

(PHP 7, PHP 8)

IntlChar::digit — コードポイントの10進の数値を、指定された基数で返す

### 説明

public static function 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'` までの範囲にある場合。 この場合、値は `codepoint - 'A' + 10` になります。
- 指定された文字が、アルファベットの小文字 `'a'` から `'z'` までの範囲にある場合。 この場合、値は `codepoint - '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", 16));
    var_dump(IntlChar::digit("A"));

    ?>

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

    int(0)
    int(3)
    int(10)
    bool(false)

### 参考

- IntlChar::forDigit() - 指定された整数と基数を表す文字を取得する
- IntlChar::charDigitValue() - 10進数の桁の文字を桁の値として取得する
- IntlChar::isdigit() - コードポイントが、数字であるかを調べる
- `IntlChar::PROPERTY_NUMERIC_TYPE`

# IntlChar::enumCharNames

(PHP 7, PHP 8)

IntlChar::enumCharNames — 指定された範囲の全てのUnicode文字を走査する

### 説明

public static function 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 文字を探し、コードポイントの値を返す

# IntlChar::enumCharTypes

(PHP 7, PHP 8)

IntlChar::enumCharTypes — Unicode の一般カテゴリの情報付きで、全てのコードポイントを走査する

### 説明

public static function 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::foldCase

(PHP 7, PHP 8)

IntlChar::foldCase — コードポイントに対してケースフォールディングを行う

### 説明

public static function 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::forDigit

(PHP 7, PHP 8)

IntlChar::forDigit — 指定された整数と基数を表す文字を取得する

### 説明

public static function 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::getBidiPairedBracket

(PHP 7, PHP 8)

IntlChar::getBidiPairedBracket — コードポイントと対になる括弧文字を取得する

### 説明

public static function IntlChar::getBidiPairedBracket(int|string `$codepoint`): int|string|null

指定された文字を、それと対になる括弧文字にマップします。

`IntlChar::PROPERTY_BIDI_PAIRED_BRACKET_TYPE !== IntlChar::BPT_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) "]"

### 注意

> 注意:

> このメソッドは、ICU version 52 以降で利用可能です。

### 参考

- IntlChar::charMirror() - コードポイントの "鏡文字" を取得する
- `IntlChar::PROPERTY_BIDI_PAIRED_BRACKET`
- `IntlChar::PROPERTY_BIDI_PAIRED_BRACKET_TYPE`

# IntlChar::getBlockCode

(PHP 7, PHP 8)

IntlChar::getBlockCode — コードポイントが含まれる割当ブロックを取得する

### 説明

public static function 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::getCombiningClass

(PHP 7, PHP 8)

IntlChar::getCombiningClass — コードポイントの合成クラスを取得する

### 説明

public static function 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)

# IntlChar::getFC_NFKC_Closure

(PHP 7, PHP 8)

IntlChar::getFC_NFKC_Closure — コードポイントの FC_NFKC_Closure プロパティの値を取得する

### 説明

public static function 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) "æ"

# IntlChar::getIntPropertyMaxValue

(PHP 7, PHP 8)

IntlChar::getIntPropertyMaxValue — Unicode プロパティの最大値を取得する

### 説明

public static function 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 のバージョンを取得する

# IntlChar::getIntPropertyMinValue

(PHP 7, PHP 8)

IntlChar::getIntPropertyMinValue — Unicode プロパティの最小値を取得する

### 説明

public static function 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 のバージョンを取得する

# IntlChar::getIntPropertyValue

(PHP 7, PHP 8)

IntlChar::getIntPropertyValue — コードポイントに対応する、Unicode プロパティの値を取得する

### 説明

public static function 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 のバージョンを取得する

# IntlChar::getNumericValue

(PHP 7, PHP 8)

IntlChar::getNumericValue — Unicode のコードポイントの数値の値を取得する

### 説明

public static function 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::getPropertyEnum

(PHP 7, PHP 8)

IntlChar::getPropertyEnum — プロパティの名前に対応する定数値を取得する

### 説明

public static function 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 での名前を取得する

# IntlChar::getPropertyName

(PHP 7, PHP 8)

IntlChar::getPropertyName — プロパティに対応する、Unicode での名前を取得する

### 説明

public static function 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::getPropertyValueEnum

(PHP 7, PHP 8)

IntlChar::getPropertyValueEnum — 指定された値の名前に対応する、プロパティの値を取得する

### 説明

public static function 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)

# IntlChar::getPropertyValueName

(PHP 7, PHP 8)

IntlChar::getPropertyValueName — プロパティの値に対応する、Unicode の名前を取得する

### 説明

public static function 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)

# IntlChar::getUnicodeVersion

(PHP 7, PHP 8)

IntlChar::getUnicodeVersion — Unicode のバージョンを取得する

### 説明

public static function 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" を取得する

# IntlChar::hasBinaryProperty

(PHP 7, PHP 8)

IntlChar::hasBinaryProperty — コードポイントに対応する、バイナリ Unicode プロパティがあるかを調べる

### 説明

public static function 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::isalnum

(PHP 7, PHP 8)

IntlChar::isalnum — コードポイントが英数字であるかを調べる

### 説明

public static function 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::isalpha

(PHP 7, PHP 8)

IntlChar::isalpha — コードポイントがアルファベットかを調べる

### 説明

public static function 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::isbase

(PHP 7, PHP 8)

IntlChar::isbase — コードポイントが基底文字に含まれるかを調べる

### 説明

public static function 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::isblank

(PHP 7, PHP 8)

IntlChar::isblank — コードポイントが "空白" または "水平方向の空白" 文字であるかを調べる

### 説明

public static function 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::iscntrl

(PHP 7, PHP 8)

IntlChar::iscntrl — コードポイントが制御文字かどうかを調べる

### 説明

public static function 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::isdefined

(PHP 7, PHP 8)

IntlChar::isdefined — コードポイントが定義されているかどうかを調べる

### 説明

public static function 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::isdigit

(PHP 7, PHP 8)

IntlChar::isdigit — コードポイントが、数字であるかを調べる

### 説明

public static function 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::isgraph

(PHP 7, PHP 8)

IntlChar::isgraph — コードポイントが図形文字であるかを調べる

### 説明

public static function 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::isIDIgnorable

(PHP 7, PHP 8)

IntlChar::isIDIgnorable — コードポイントが無視できる文字かを調べる

### 説明

public static function 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::isIDPart

(PHP 7, PHP 8)

IntlChar::isIDPart — コードポイントが識別子として使えるかを調べる

### 説明

public static function 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::isIDStart

(PHP 7, PHP 8)

IntlChar::isIDStart — コードポイントが識別子の最初の文字として使えるかを調べる

### 説明

public static function 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`

# IntlChar::isISOControl

(PHP 7, PHP 8)

IntlChar::isISOControl — コードポイントがISOで定義された制御文字であるかを調べる

### 説明

public static function 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() - コードポイントが制御文字かどうかを調べる

# IntlChar::isJavaIDPart

(PHP 7, PHP 8)

IntlChar::isJavaIDPart — コードポイントが、Java の識別子として使えるかを調べる

### 説明

public static function 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() - コードポイントが、数字であるかを調べる

# IntlChar::isJavaIDStart

(PHP 7, PHP 8)

IntlChar::isJavaIDStart — コードポイントが Java の識別子の最初の文字として使えるかを調べる

### 説明

public static function 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() - コードポイントがアルファベットかを調べる

# IntlChar::isJavaSpaceChar

(PHP 7, PHP 8)

IntlChar::isJavaSpaceChar — コードポイントが Java におけるスペース文字であるかを調べる

### 説明

public static function 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::islower

(PHP 7, PHP 8)

IntlChar::islower — コードポイントが小文字かどうかを調べる

### 説明

public static function 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() - 小文字かどうかを調べる

# IntlChar::isMirrored

(PHP 7, PHP 8)

IntlChar::isMirrored — コードポイントが Bidi_Mirrored プロパティを持つかを調べる

### 説明

public static function 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::isprint

(PHP 7, PHP 8)

IntlChar::isprint — コードポイントが印字可能な文字かを調べる

### 説明

public static function 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::ispunct

(PHP 7, PHP 8)

IntlChar::ispunct — コードポイントが句読点の文字かどうかを調べる

### 説明

public static function 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::isspace

(PHP 7, PHP 8)

IntlChar::isspace — コードポイントが、スペース文字であるかを調べる

### 説明

public static function 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::istitle

(PHP 7, PHP 8)

IntlChar::istitle — コードポイントがタイトルケース文字であるかを調べる

### 説明

public static function 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 文字をタイトルケースにする

# IntlChar::isUAlphabetic

(PHP 7, PHP 8)

IntlChar::isUAlphabetic — コードポイントが、Alphabetic プロパティを持つかを調べる

### 説明

public static function 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`

# IntlChar::isULowercase

(PHP 7, PHP 8)

IntlChar::isULowercase — コードポイントが小文字のUnicodeプロパティを持つかを調べる

### 説明

public static function 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`

# IntlChar::isupper

(PHP 7, PHP 8)

IntlChar::isupper — コードポイントが一般カテゴリ "Lu" (大文字) に属するかを判定する

### 説明

public static function 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() - 大文字かどうか調べる

# IntlChar::isUUppercase

(PHP 7, PHP 8)

IntlChar::isUUppercase — コードポイントが大文字のUnicodeプロパティを持つかを調べる

### 説明

public static function 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`

# IntlChar::isUWhiteSpace

(PHP 7, PHP 8)

IntlChar::isUWhiteSpace — コードポイントが、White_Space プロパティを持つかを調べる

### 説明

public static function 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`

# IntlChar::isWhitespace

(PHP 7, PHP 8)

IntlChar::isWhitespace — コードポイントが、ICU の空白文字であるかを調べる

### 説明

public static function 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 プロパティを持つかを調べる

# IntlChar::isxdigit

(PHP 7, PHP 8)

IntlChar::isxdigit — コードポイントが、16進数の文字であるかを調べる

### 説明

public static function 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 進数を表す文字かどうかを調べる

# IntlChar::ord

(PHP 7, PHP 8)

IntlChar::ord — 文字に対応する Unicode コードポイントを返す

### 説明

public static function 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 までの値に変換する

# IntlChar::tolower

(PHP 7, PHP 8)

IntlChar::tolower — Unicode 文字を小文字にする

### 説明

public static function 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() - 文字列を小文字にする

# IntlChar::totitle

(PHP 7, PHP 8)

IntlChar::totitle — Unicode 文字をタイトルケースにする

### 説明

public static function 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() - 文字列に対してケースフォールディングを行う

# IntlChar::toupper

(PHP 7, PHP 8)

IntlChar::toupper — Unicode 文字を大文字にする

### 説明

public static function 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() - 文字列を大文字にする

## 目次

- 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 文字を大文字にする

# 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 function Exception::__construct(string `$message` = "", int `$code` = 0, ?Throwable `$previous` = `null`)
final public function Exception::getMessage(): string
final public function Exception::getPrevious(): ?Throwable
final public function Exception::getCode(): int
final public function Exception::getFile(): string
final public function Exception::getLine(): int
final public function Exception::getTrace(): array
final public function Exception::getTraceAsString(): string
public function Exception::__toString(): string
private function Exception::__clone(): void
}

# IntlIterator クラス

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

## はじめに

このクラスは、intl 拡張モジュール全体を通じて、 拡張モジュールが提供する他のいかなるオブジェクトでも認識できない イテレータを表現します。 言語構造 `foreach` によって内部的に使われる独自のイテレータは、 オブジェクトからのみ取得できます。よって、 このクラスのインスタンスは、 この内部オブジェクトが取得できるフックを提供する役割を果たします。 便宜のため、 このクラスは Iterator インターフェイスも実装しています。 これによって、 値の集合をこのインターフェイスのメソッドを使って走査することができます。 これらのメソッドも、 `foreach` に提供される内部的なイテレータオブジェクトも、 同じ状態 (つまり、イテレータの位置と現在の値) を持っています。

このクラスのサブクラスは、 もっと豊かな機能を提供しています。

## クラス概要

class IntlIterator implements Iterator {
/* メソッド */
public function current(): mixed
public function key(): mixed
public function next(): void
public function rewind(): void
public function valid(): bool
}

# IntlIterator::current

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::current — 現在の要素を取得する

### 説明

public function IntlIterator::current(): mixed

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# IntlIterator::key

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::key — 現在のキーを取得する

### 説明

public function IntlIterator::key(): mixed

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# IntlIterator::next

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::next — 次の要素に進む

### 説明

public function IntlIterator::next(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# IntlIterator::rewind

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::rewind — イテレータを最初の要素に戻す

### 説明

public function IntlIterator::rewind(): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# IntlIterator::valid

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

IntlIterator::valid — 現在の位置が有効かを調べる

### 説明

public function IntlIterator::valid(): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

## 目次

- IntlIterator::current — 現在の要素を取得する
- IntlIterator::key — 現在のキーを取得する
- IntlIterator::next — 次の要素に進む
- IntlIterator::rewind — イテレータを最初の要素に戻す
- IntlIterator::valid — 現在の位置が有効かを調べる

# 国際化 関数

# intl_error_name

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_error_name — 指定したエラーコードに対応する名前を取得する

### 説明

function 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_get_error_code

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_get_error_code — 直近のエラーコードを取得する

### 説明

function 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_message

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_get_error_message — 直近のエラーの説明を取得する

### 説明

function 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_is_failure

(PHP 5 >= 5.3.0, PHP 7, PHP 8, PECL intl >= 1.0.0)

intl_is_failure — 指定したエラーコードが失敗を表すかどうかを調べる

### 説明

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

## 目次

- intl_error_name — 指定したエラーコードに対応する名前を取得する
- intl_get_error_code — 直近のエラーコードを取得する
- intl_get_error_message — 直近のエラーの説明を取得する
- intl_is_failure — 指定したエラーコードが失敗を表すかどうかを調べる

- インストール/設定
  - 要件
  - インストール手順
  - 実行時設定
- 定義済み定数
- 例
  - 基本的な使用法
- 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::isRightToLeft — ロケールが右から左に書く文字体系を使うかどうかを調べる
  - 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::getIanaID — タイムゾーン識別子を、対応する IANA 識別子に変換する
  - 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::parseToCalendar — 文字列をパースしてタイムスタンプにし、使用中のカレンダーを更新する
  - 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::setAllowedChars — チェック時に許可する文字集合を設定する
  - 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_str_split — 書記素クラスターを受け取り、文字の配列を返す
  - 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 — 指定したエラーコードが失敗を表すかどうかを調べる

# マルチバイト文字列

# はじめに

全ての文字をシングルバイトで一対一表現可能な言語は数多くありますが、 文字表現に単一バイトによる表現範囲を越えるほど多くの文字を必要とする言語も多くあります (1 バイトは 8 ビットから構成されます。各ビットには、1 あるいは 0 の 2 種類の値しか保持できません。そのため、単一のバイトで表すことのできる値は 256 (2 の 8 乗) 種類までとなります)。 マルチバイト文字のエンコーディング法は、 256 を越える文字を通常のビット単位の符号化システムで表現するために開発されました。

マルチバイトエンコーディングで符号化された文字列を (trim, split, splice などで) 処理する際、こうしたエンコーディングでは二つ以上の連続するバイトが 一つの文字を表す可能性があるため、特別な関数を使用する必要があります。 マルチバイトに対応しない文字列関数を文字列に適用した場合、 マルチバイト文字の先頭バイトまたは終了バイトを検出できずに文字列を壊し、 多くの場合には元の意味を失わせてしまう可能性があります。

`mbstring` はマルチバイト対応の文字列関数を提供し、 PHP でマルチバイトエンコーディングを処理することを容易にします。 それに加えて、`mbstring` は、 可能な範囲での文字エンコーディングの変換を処理します。 `mbstring` は UTF-8 や UCS-2 のような Unicode に基づくエンコーディングや多くのシングルバイトエンコーディングを処理するのに便利です (サポートされる文字エンコーディング に一覧があります)。

# インストール/設定

## 目次

- インストール手順
- 実行時設定

## インストール手順

`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

(PHP 4 >= 4.4.3, PHP 5 >= 5.1.3, PHP 7, PHP 8)

mb_check_encoding — 文字列が、指定したエンコーディングで有効なものかどうかを調べる

### 説明

function 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` に配列を受け入れるようになりました。 このバージョンより前では、文字列のみがサポートされていました。

# mb_chr

(PHP 7 >= 7.2.0, PHP 8)

mb_chr — Unicode のコードポイントに対応する文字を返す

### 説明

function 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_convert_case

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_convert_case — 文字列に対してケースフォールディングを行う

### 説明

function 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` に対してケースフォールディングを行った結果を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.3.0 | ギリシャ文字のシグマ向けに、条件付きのケースルールが実装されました。 これは `MB_CASE_LOWER` と `MB_CASE_TITLE` にのみ適用されます。 `MB_CASE_LOWER_SIMPLE` と `MB_CASE_TITLE_SIMPLE` には適用されません。
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, PHP_EOL;
    $str = mb_convert_case($str, MB_CASE_TITLE, "UTF-8");
    echo $str, PHP_EOL;
    ?>

例2 非ラテン UTF-8 テキストでの mb_convert_case() の例

    <?php
    $str = "Τάχιστη αλώπηξ βαφής ψημένη γη, δρασκελίζει υπέρ νωθρού κυνός";
    $str = mb_convert_case($str, MB_CASE_UPPER, "UTF-8");
    echo $str, PHP_EOL;
    $str = mb_convert_case($str, MB_CASE_TITLE, "UTF-8");
    echo $str, PHP_EOL;
    ?>

### Unicode

標準のケースフォールディング関数である strtolower() や strtoupper() と違い、ケースフォールディングは Unicode 文字属性を基準に行われます。したがって、この関数の挙動は ロケールの設定に影響されず、また、すべてのアルファベット、 例えば A ウムラウト (Ä) を変換することができます。

Unicode 文字属性についての詳細は » http://www.unicode.org/reports/tr21/ を参照ください。

### 参考

- mb_strtolower() - 文字列を小文字にする
- mb_strtoupper() - 文字列を大文字にする
- strtolower() - 文字列を小文字にする
- strtoupper() - 文字列を大文字にする
- ucfirst() - 文字列の最初の文字を大文字にする
- ucwords() - 文字列の各単語の最初の文字を大文字にする

# mb_convert_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_encoding — ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する

### 説明

function 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_kana

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_kana — カナを("全角かな"、"半角かな"等に)変換する

### 説明

function 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
    /* Convert all "han-kaku" "kata-kana" to "zen-kaku" "hira-gana" */
    echo mb_convert_kana('ﾔﾏﾀﾞ ﾊﾅｺ', "HV") . "\n";

    /* Convert "han-kaku" "kata-kana" to "zen-kaku" "kata-kana"
       and "zen-kaku" alphanumeric to "han-kaku" */
    echo mb_convert_kana('ｺｳｻﾞﾊﾞﾝｺﾞｳ ０１２３４５６', "KVa") . "\n";
    ?>

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

    やまだ はなこ
    コウザバンゴウ 0123456

# mb_convert_variables

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_convert_variables — 変数の文字コードを変換する

### 説明

function 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);
    ?>

# mb_decode_mimeheader

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_decode_mimeheader — MIME ヘッダフィールドの文字列をデコードする

### 説明

function mb_decode_mimeheader(string `$string`): string

エンコードされた MIME ヘッダの文字列 `string` をデコードします。

### パラメータ

`string`

  デコードする文字列。

### 戻り値

内部文字エンコーディングでデコードされた文字列を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.3.0 | アンダースコアは » RFC 2047 に定められた通り、スペースに変換されるようになりました。

### 参考

- mb_encode_mimeheader() - MIMEヘッダの文字列をエンコードする

# mb_decode_numericentity

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_decode_numericentity — HTML 数値エンティティを文字にデコードする

### 説明

function mb_decode_numericentity(string `$string`, array `$map`, ?string `$encoding` = `null`): string

文字列 `string` において指定した文字領域にある数値エンティティを変換し、 変換後の文字列を返します。

### パラメータ

`string`

  デコードする文字列。

`map`

  `map` は変換するコード領域を指定する配列です。

`encoding`
  `encoding` パラメータには文字エンコーディングを指定します。省略した場合、もしくは `null` の場合は、 内部文字エンコーディングを使用します。

### 戻り値

変換された文字列を返します。

### エラー / 例外

`map` が整数のリストでない場合、 ValueError がスローされます。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `map` が整数のリストでない場合、 mb_decode_numericentity() は ValueError をスローするようになりました。
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_detect_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_detect_encoding — 文字エンコーディングを検出する

### 説明

function mb_detect_encoding(string `$string`, array|string|null `$encodings` = `null`, bool `$strict` = `false`): string|false

エンコーディングの候補の一覧から、 文字列 `string` のもっとも可能性が高い文字エンコーディングを検出します。

PHP 8.1 以降では、 この関数は指定されたテキスト中の有効なテキストエンコーディングのうち、 もっとも正しい可能性が高いものを、経験則を用いて検出します。 そのため、`encodings` の順番通りでない場合があります。

追加の情報なしに、 意図した文字エンコーディングを自動で検出する行為は、 全く役に立ちません。 これは、暗号化された文字列を鍵なしにデコードする行為に似ています。 "Content-Type" HTTP ヘッダのような、 データを転送された際に付いてくる情報や、 保存された文字エンコーディングに関する指示を指定することが常に望ましいです。

この関数は、全ての文字列が正しいバイト配列とは限らない マルチバイト文字列を指定するともっとも役に立ちます。 入力となる文字列に誤ったバイトが含まれていた場合、 そのエンコーディングは採用されません。

警告

# この関数の結果は正確ではありません

この関数の名前は誤解を招きやすいです。 この関数は 「検出」(detection) ではなく 「推測」"guessing" を行います。

この関数が行う「推測」は正確には程遠いので、 正しい文字エンコーディングを検出する用途に、この関数は使えません。

### パラメータ

`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

    $str = "\x95\xB6\x8E\x9A\x83\x52\x81\x5B\x83\x68";

    // 現在のdetect_orderで文字エンコーディングを検出
    var_dump(mb_detect_encoding($str));

    // "auto" は mbstring.language の設定を使って展開されます
    var_dump(mb_detect_encoding($str, "auto"));

    // 文字エンコーディングをカンマ区切りのリストで指定することで、encodings 引数を指定
    var_dump(mb_detect_encoding($str, "JIS, eucjp-win, sjis-win"));

    // encodings 引数を配列で指定
    $encodings = [
      "ASCII",
      "JIS",
      "EUC-JP"
    ];
    var_dump(mb_detect_encoding($str, $encodings));
    ?>

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

    string(5) "ASCII"
    string(5) "ASCII"
    string(8) "SJIS-win"
    string(5) "ASCII"

例2 `strict` パラメーターの効果

    <?php
    // 'áéóú' は 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" は、 以下のように解釈できます:

- "Ä¢" (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']));
    var_dump(mb_detect_encoding($str, ['UTF-8', 'ISO-8859-1', 'ISO-8859-5'])); // PHP 8.1 以降では、UTF-8 ではなく ISO-8859-1 が返されます
    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-1"
    string(10) "ISO-8859-5"

### 参考

- mb_detect_order() - 文字エンコーディング検出順序を設定あるいは取得する

# mb_detect_order

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_detect_order — 文字エンコーディング検出順序を設定あるいは取得する

### 説明

function 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() - エンコード変換を行ってメールを送信する

# mb_encode_mimeheader

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_encode_mimeheader — MIMEヘッダの文字列をエンコードする

### 説明

function 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.3.0 | `NUL` (0) バイトは、 Quoted-Printable エンコーディングを用いた場合でも削除されなくなりました。 代わりに、`=00` でエンコードされます。
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 ヘッダフィールドの文字列をデコードする

# mb_encode_numericentity

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_encode_numericentity — 文字を HTML 数値エンティティにエンコードする

### 説明

function 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進記法です)

### 戻り値

変換後の文字列を返します。

### エラー / 例外

`map` が整数のリストでない場合、 ValueError がスローされます。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `map` が整数のリストでない場合、 mb_encode_numericentity() は ValueError をスローするようになりました。
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 );
    // Specify Unicode value for start_codeN and end_codeN
    // Add offsetN to value and take bit-wise 'AND' with maskN, then
    // it converts value to numeric string reference.
    ?>

例2 mb_encode_numericentity() の例

    <?php

    $str = "aAæÆあア𩸽";

    /* Convert all UTF8 characters up to 4 bytes to HTML numeric character reference */
    $convmap = [0, 0x1FFFFF, 0, 0x10FFFF];
    var_dump(mb_encode_numericentity($str, $convmap, "utf8"));

    /* Converts only 2-byte and 4-byte UTF8 characters to HTML numeric character reference */
    $convmap = [
        0x80, 0x7FF, 0, 0x10FFFF,
        0x10000, 0x1FFFFF, 0, 0x10FFFF,
    ];
    var_dump(mb_encode_numericentity($str, $convmap, "utf8"));
    ?>

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

    string(46) "&#97;&#65;&#230;&#198;&#12354;&#12450;&#40509;"
    string(28) "aA&#230;&#198;あア&#40509;"

### 参考

- mb_decode_numericentity() - HTML 数値エンティティを文字にデコードする

# mb_encoding_aliases

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

mb_encoding_aliases — 既知のエンコーディング・タイプのエイリアスを取得

### 説明

function 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_ereg

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg — マルチバイト対応の正規表現マッチ

### 説明

function mb_ereg(string `$pattern`, string `$string`, array `&$matches` = `null`): bool

マルチバイト対応の正規表現マッチを行います。

### パラメータ

`pattern`

  検索パターン。

`string`

  検索する 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` を空のarrayとするようになりました。 これより前のバージョンでは `matches` を変更しませんでした。

### 注意

> 注意: 内部エンコーディングあるいは mb_regex_encoding() で指定した文字エンコーディングを、 この関数の文字エンコーディングとして使用します。

### 参考

- mb_regex_encoding() - 現在のマルチバイト正規表現用のエンコーディングを取得または設定する
- mb_eregi() - マルチバイトをサポートし、大文字小文字を無視した正規表現マッチ

# mb_ereg_match

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_match — マルチバイト文字列が正規表現に一致するか調べる

### 説明

function 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_replace

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_replace — マルチバイト文字列に正規表現による置換を行う

### 説明

function 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_callback

(PHP 5 >= 5.4.1, PHP 7, PHP 8)

mb_ereg_replace_callback — マルチバイト文字列にコールバック関数を用いた正規表現による置換を行う

### 説明

function 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_search

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search — 指定したマルチバイト文字列が正規表現に一致するか調べる

### 説明

function 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_getpos

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_getpos — 次の正規表現検索を開始する位置を取得する

### 説明

function 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_getregs

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_getregs — マルチバイト文字列が正規表現に一致する部分があるか調べる

### 説明

function 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_init

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_init — マルチバイト正規表現検索用の文字列と正規表現を設定する

### 説明

function 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_pos

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_pos — 指定したマルチバイト文字列が正規表現に一致する部分の位置と長さを返す

### 説明

function 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_regs

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_regs — 指定したマルチバイト文字列が正規表現に一致する部分を取得する

### 説明

function 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_setpos

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_ereg_search_setpos — 次の正規表現検索を開始する位置を設定する

### 説明

function 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_eregi

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_eregi — マルチバイトをサポートし、大文字小文字を無視した正規表現マッチ

### 説明

function 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_replace

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_eregi_replace — マルチバイト文字列に大文字小文字を区別せずに正規表現による置換を行う

### 説明

function 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() - マルチバイト文字列に正規表現による置換を行う

# mb_get_info

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_get_info — mbstring の内部設定値を取得する

### 説明

function 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 出力文字エンコーディングを設定あるいは取得する

# mb_http_input

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_http_input — HTTP 入力文字エンコーディングを検出する

### 説明

function 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` を返します。

### エラー / 例外

`type` が不正な場合、 ValueError がスローされます。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `type` が不正な場合、 mb_http_input() は ValueError をスローするようになりました。
8.0.0 | `type` は、nullable になりました。

### 参考

- mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する
- mb_http_output() - HTTP 出力文字エンコーディングを設定あるいは取得する
- mb_detect_order() - 文字エンコーディング検出順序を設定あるいは取得する

# mb_http_output

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_http_output — HTTP 出力文字エンコーディングを設定あるいは取得する

### 説明

function 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` を返します。

### エラー / 例外

`encoding` にヌルバイトが含まれている場合、 ValueError がスローされます。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `encoding` にヌルバイトが含まれている場合、 mb_http_output() は ValueError をスローするようになりました。
8.0.0 | `encoding` は、nullable になりました。

### 参考

- mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する
- mb_http_input() - HTTP 入力文字エンコーディングを検出する
- mb_detect_order() - 文字エンコーディング検出順序を設定あるいは取得する

# mb_internal_encoding

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_internal_encoding — 内部文字エンコーディングを設定あるいは取得する

### 説明

function 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_language

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_language — 現在の言語を設定あるいは取得する

### 説明

function 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_lcfirst

(PHP 8 >= 8.4.0)

mb_lcfirst — 文字列の最初の文字を小文字にする

### 説明

function mb_lcfirst(string `$string`, ?string `$encoding` = `null`): string

マルチバイト対応の lcfirst() 処理を行い、 `string` の最初の文字を小文字に変換して返します。

### パラメータ

`string`
  入力文字列。
`encoding`
  `encoding` パラメータには文字エンコーディングを指定します。省略した場合、もしくは `null` の場合は、 内部文字エンコーディングを使用します。

### 戻り値

変換後の文字列を返します。

### 参考

- mb_ucfirst() - 文字列の最初の文字を大文字にする
- lcfirst() - 文字列の最初の文字を小文字にする

# mb_list_encodings

(PHP 5, PHP 7, PHP 8)

mb_list_encodings — サポートするすべてのエンコーディングの配列を返す

### 説明

function 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() - 既知のエンコーディング・タイプのエイリアスを取得

# mb_ltrim

(PHP 8 >= 8.4.0)

mb_ltrim — 文字列の先頭にあるホワイトスペースを取り除く

### 説明

function mb_ltrim(string `$string`, ?string `$characters` = `null`, ?string `$encoding` = `null`): string

マルチバイト対応の ltrim() 処理を行い、 `string`の最初から空白文字を取り除き、 取り除かれた文字列を返します。

2番目のパラメータを指定しない場合、 mb_ltrim() は以下の文字を削除します。

- `" "` (Unicode U+0020)、通常のスペース。
- `"\t"` (Unicode U+0009)、タブ。
- `"\n"` (Unicode U+000A)、改行（ラインフィード）。
- `"\r"` (Unicode U+000D)、キャリッジリターン。
- `"\0"` (Unicode U+0000)、NULバイト。
- `"\v"` (Unicode U+000B)、垂直タブ。
- `"\f"` (Unicode U+000C)、フォームフィード。
- `"\u00A0"` (Unicode U+00A0)、ノーブレークスペース。もしくは、非分割スペース。
- `"\u1680"` (Unicode U+1680)、オガム文字（古代アイルランド語）用のスペース。
- `"\u2000"` (Unicode U+2000)、エンクアッド。アルファベット1文字分の幅を持つスペース。
- `"\u2001"` (Unicode U+2001)、エムクアッド。エンクアッドの2倍の幅を持つスペース。
- `"\u2002"` (Unicode U+2002)、エンスペース。エンクアッドと同じ幅のスペース。
- `"\u2003"` (Unicode U+2003)、エムスペース。エムクアッドと同じ幅のスペース。
- `"\u2004"` (Unicode U+2004)、エムスペースの3分の1の幅を持つスペース。
- `"\u2005"` (Unicode U+2005)、エムスペースの4分の1の幅を持つスペース。
- `"\u2006"` (Unicode U+2006)、エムスペースの6分の1の幅を持つスペース。
- `"\u2007"` (Unicode U+2007)、数字や図の間隔を整えるために使われるスペース。
- `"\u2008"` (Unicode U+2008)、句読点のためにデザインされたスペース。
- `"\u2009"` (Unicode U+2009)、シンスペース。非常に狭いスペース。
- `"\u200A"` (Unicode U+200A)、ヘアスペース。シンスペースよりもさらに細いスペース。
- `"\u2028"` (Unicode U+2028)、ラインセパレーター。行の区切りとして使用。
- `"\u2029"` (Unicode U+2029)、パラグラフセパレーター。段落の区切りとして使用。
- `"\u202F"` (Unicode U+202F)、ナローノーブレークスペース。通常の非分割スペースよりも狭く、ラテン文字や句読点の間で使用。
- `"\u205F"` (Unicode U+205F)、数式などで使われるスペース。
- `"\u3000"` (Unicode U+3000)、全角文字用のスペース。
- `"\u0085"` (Unicode U+0085)、次行（NEL）。
- `"\u180E"` (Unicode U+180E)、モンゴル語のテキスト内で母音を区切るために使用されるスペース。

### パラメータ

`string`
  ホワイトスペースを取り除くstring。
`characters`
  `characters` パラメータにより、 削除する文字を指定することも可能です。 削除したい全ての文字をリストにしてください。
`encoding`
  `encoding` パラメータには文字エンコーディングを指定します。省略した場合、もしくは `null` の場合は、 内部文字エンコーディングを使用します。

### 戻り値

トリム処理を行った文字列を返します。

### 参考

- mb_trim() - 文字列の先頭および末尾にあるホワイトスペースを取り除く
- mb_rtrim() - 文字列の末尾にあるホワイトスペースを取り除く
- ltrim() - 文字列の最初から空白 (もしくはその他の文字) を取り除く

# mb_ord

(PHP 7 >= 7.2.0, PHP 8)

mb_ord — 文字の Unicode コードポイントを取得する

### 説明

function 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_output_handler

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_output_handler — 出力バッファ内で文字エンコーディングを変換するコールバック関数

### 説明

function 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() - 出力のバッファリングを有効にする

# mb_parse_str

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_parse_str — GET/POST/COOKIE データをパースし、グローバル変数を設定する

### 説明

function 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() - 内部文字エンコーディングを設定あるいは取得する

# mb_preferred_mime_name

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_preferred_mime_name — MIME 文字設定を文字列で得る

### 説明

function 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_regex_encoding

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_regex_encoding — 現在のマルチバイト正規表現用のエンコーディングを取得または設定する

### 説明

function 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_set_options

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_regex_set_options — マルチバイト正規表現関数のデフォルトオプションを取得または設定する

### 説明

function 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_rtrim

(PHP 8 >= 8.4.0)

mb_rtrim — 文字列の末尾にあるホワイトスペースを取り除く

### 説明

function mb_rtrim(string `$string`, ?string `$characters` = `null`, ?string `$encoding` = `null`): string

マルチバイト対応の rtrim() 処理を行い, `string`の最後から空白文字を取り除き、 取り除かれた文字列を返します。

2番目のパラメータを指定しない場合、 mb_rtrim() は以下の文字を削除します。

- `" "` (Unicode U+0020)、通常のスペース。
- `"\t"` (Unicode U+0009)、タブ。
- `"\n"` (Unicode U+000A)、改行（ラインフィード）。
- `"\r"` (Unicode U+000D)、キャリッジリターン。
- `"\0"` (Unicode U+0000)、NULバイト。
- `"\v"` (Unicode U+000B)、垂直タブ。
- `"\f"` (Unicode U+000C)、フォームフィード。
- `"\u00A0"` (Unicode U+00A0)、ノーブレークスペース。もしくは、非分割スペース。
- `"\u1680"` (Unicode U+1680)、オガム文字（古代アイルランド語）用のスペース。
- `"\u2000"` (Unicode U+2000)、エンクアッド。アルファベット1文字分の幅を持つスペース。
- `"\u2001"` (Unicode U+2001)、エムクアッド。エンクアッドの2倍の幅を持つスペース。
- `"\u2002"` (Unicode U+2002)、エンスペース。エンクアッドと同じ幅のスペース。
- `"\u2003"` (Unicode U+2003)、エムスペース。エムクアッドと同じ幅のスペース。
- `"\u2004"` (Unicode U+2004)、エムスペースの3分の1の幅を持つスペース。
- `"\u2005"` (Unicode U+2005)、エムスペースの4分の1の幅を持つスペース。
- `"\u2006"` (Unicode U+2006)、エムスペースの6分の1の幅を持つスペース。
- `"\u2007"` (Unicode U+2007)、数字や図の間隔を整えるために使われるスペース。
- `"\u2008"` (Unicode U+2008)、句読点のためにデザインされたスペース。
- `"\u2009"` (Unicode U+2009)、シンスペース。非常に狭いスペース。
- `"\u200A"` (Unicode U+200A)、ヘアスペース。シンスペースよりもさらに細いスペース。
- `"\u2028"` (Unicode U+2028)、ラインセパレーター。行の区切りとして使用。
- `"\u2029"` (Unicode U+2029)、パラグラフセパレーター。段落の区切りとして使用。
- `"\u202F"` (Unicode U+202F)、ナローノーブレークスペース。通常の非分割スペースよりも狭く、ラテン文字や句読点の間で使用。
- `"\u205F"` (Unicode U+205F)、数式などで使われるスペース。
- `"\u3000"` (Unicode U+3000)、全角文字用のスペース。
- `"\u0085"` (Unicode U+0085)、次行（NEL）。
- `"\u180E"` (Unicode U+180E)、モンゴル語のテキスト内で母音を区切るために使用されるスペース。

### パラメータ

`string`
  ホワイトスペースを取り除くstring>。
`characters`
  `characters` パラメータにより、 削除する文字を指定することも可能です。 削除したい全ての文字をリストにしてください。
`encoding`
  `encoding` パラメータには文字エンコーディングを指定します。省略した場合、もしくは `null` の場合は、 内部文字エンコーディングを使用します。

### 戻り値

トリム処理を行った文字列を返します。

### 参考

- mb_trim() - 文字列の先頭および末尾にあるホワイトスペースを取り除く
- mb_ltrim() - 文字列の先頭にあるホワイトスペースを取り除く
- rtrim() - 文字列の最後から空白 (もしくはその他の文字) を取り除く

# mb_scrub

(PHP 7 >= 7.2.0, PHP 8)

mb_scrub — 文字列に含まれる不正なバイト列を代替文字に置き換える

### 説明

function mb_scrub(string `$string`, ?string `$encoding` = `null`): string

指定されたエンコーディングに基づいて、文字の変換を行います。 エンコーディングが指定されない場合は、 デフォルトのエンコーディングが使われます。 この関数は、不正なバイトシーケンスを代替文字に置換する効果があります。

### パラメータ

`string`

  入力文字列

`encoding`

  `string` を解釈するエンコーディング。 省略されるか、`null` でない場合は、 mbstring.internal_encoding setting が設定されている場合、それを使います。 設定されていない場合は、default_charset の設定を使います。

### 戻り値

不正なバイトシーケンスを置換した文字列を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `encoding` は、nullable になりました。

# mb_send_mail

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_send_mail — エンコード変換を行ってメールを送信する

### 説明

function 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_split

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

mb_split — マルチバイト文字列を正規表現により分割する

### 説明

function 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() - マルチバイト対応の正規表現マッチ
- explode() - 文字列を文字列により分割する

# mb_str_pad

(PHP 8 >= PHP 8.3.0)

mb_str_pad — マルチバイト文字列を、特定の長さまで別のマルチバイト文字列で埋める

### 説明

function 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_split

(PHP 7 >= 7.4.0, PHP 8)

mb_str_split — マルチバイト文字列を受取り、文字の配列を返す

### 説明

function 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() - 文字列を配列に変換する
- grapheme_str_split() - 書記素クラスターを受け取り、文字の配列を返す
- explode() - 文字列を文字列により分割する

# mb_strcut

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strcut — 文字列の一部を得る

### 説明

function 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.4.0 | 不正な `UTF-8` および `UTF-16` 文字列に対する挙動が、より一貫したものになりました。
8.0.0 | `encoding` は、nullable になりました。

### 参考

- mb_substr() - 文字列の一部を得る
- mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する

# mb_strimwidth

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strimwidth — 指定した幅で文字列を丸める

### 説明

function 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_stripos

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_stripos — 大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す

### 説明

function 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`
  `encoding` パラメータには文字エンコーディングを指定します。省略した場合、もしくは `null` の場合は、 内部文字エンコーディングを使用します。

### 戻り値

`needle` が `haystack` の中で最初に現れる位置を返します。`needle` が見つからない場合は `false` を返します。

### エラー / 例外

- `offset` が `haystack` の長さより大きい場合、 ValueError がスローされます。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `needle` は、空の文字列も受け入れるようになりました。
8.0.0 | `encoding` は、nullable になりました。
7.1.0 | 負の `offset` をサポートするようになりました。

### 参考

- stripos() - 大文字小文字を区別せずに文字列が最初に現れる位置を探す
- strpos() - 文字列内の部分文字列が最初に現れる場所を見つける
- mb_strpos() - 文字列の中に指定した文字列が最初に現れる位置を見つける

# mb_stristr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_stristr — 大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す

### 説明

function 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`
  `encoding` パラメータには文字エンコーディングを指定します。省略した場合、もしくは `null` の場合は、 内部文字エンコーディングを使用します。

### 戻り値

`haystack` の部分文字列を返します。 `needle` が見つからない場合は `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `needle` は、空の文字列も受け入れるようになりました。
8.0.0 | `encoding` は、nullable になりました。

### 参考

- stristr() - 大文字小文字を区別しない strstr
- strstr() - 文字列が最初に現れる位置を見つける
- mb_strstr() - 文字列の中で、指定した文字列が最初に現れる位置を見つける

# mb_strlen

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strlen — 文字列の長さを得る

### 説明

function 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_strpos

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strpos — 文字列の中に指定した文字列が最初に現れる位置を見つける

### 説明

function mb_strpos(
string `$haystack`,
string `$needle`,
int `$offset` = 0,
?string `$encoding` = `null`
): int|false

`haystack` の中で `needle` 文字列が最初に現れる位置を見つけます。

マルチバイト文字列に正しくマッチするように strpos() を拡張したもので、 最初の 1 文字目の位置が 0 、2 文字目の文字が 1 というようになります。

### パラメータ

`haystack`

  `needle` が最初に現れる位置を調べたい文字列。

`needle`

  `haystack` の中から探す文字列。 strpos() とは違い、 数値を指定しても文字コードの値と見なされることはありません。

`offset`

  検索オフセット。 指定されない場合は、0 が使用されます。 負のオフセットは、文字列の末尾からのオフセットと解釈されます。

`encoding`
  `encoding` パラメータには文字エンコーディングを指定します。省略した場合、もしくは `null` の場合は、 内部文字エンコーディングを使用します。

### 戻り値

文字列 `haystack` の中で `needle` が最初に現れる位置を数字で返します。 `needle` が見付からなかった場合、`false` を返します。

### エラー / 例外

- `offset` が `haystack` の長さより大きい場合、 ValueError がスローされます。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `needle` は、空の文字列も受け入れるようになりました。
8.0.0 | `encoding` は、nullable になりました。
7.1.0 | 負の `offset` をサポートするようになりました。

### 参考

- mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する
- strpos() - 文字列内の部分文字列が最初に現れる場所を見つける

# mb_strrchr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strrchr — 別の文字列の中で、ある文字が最後に現れる場所を見つける

### 説明

function 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`
  `encoding` パラメータには文字エンコーディングを指定します。省略した場合、もしくは `null` の場合は、 内部文字エンコーディングを使用します。

### 戻り値

`haystack` の部分文字列を返します。 `needle` が見つからない場合は `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `needle` は、空の文字列も受け入れるようになりました。
8.0.0 | `encoding` は、nullable になりました。

### 参考

- strrchr() - 文字列中に文字が最後に現れる場所を取得する
- mb_strstr() - 文字列の中で、指定した文字列が最初に現れる位置を見つける
- mb_strrichr() - 大文字小文字を区別せず、 別の文字列の中である文字が最後に現れる場所を探す

# mb_strrichr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strrichr — 大文字小文字を区別せず、 別の文字列の中である文字が最後に現れる場所を探す

### 説明

function 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`
  `encoding` パラメータには文字エンコーディングを指定します。省略した場合、もしくは `null` の場合は、 内部文字エンコーディングを使用します。

### 戻り値

`haystack` の部分文字列を返します。 `needle` が見つからない場合は `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `needle` は、空の文字列も受け入れるようになりました。
8.0.0 | `encoding` は、nullable になりました。

### 参考

- mb_stristr() - 大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す
- mb_strrchr() - 別の文字列の中で、ある文字が最後に現れる場所を見つける

# mb_strripos

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strripos — 大文字小文字を区別せず、 文字列の中で指定した文字列が最後に現れる位置を探す

### 説明

function 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` 内の任意の文字数から検索を開始するために指定します。 負の値を指定すると、 `haystack` の末尾より前の任意の地点で検索が停止します。

`encoding`
  `encoding` パラメータには文字エンコーディングを指定します。省略した場合、もしくは `null` の場合は、 内部文字エンコーディングを使用します。

### 戻り値

`needle` が `haystack` の中で最後に現れる位置を返します。`needle` が見つからない場合は `false` を返します。

### エラー / 例外

- `offset` が `haystack` の長さより大きい場合、 ValueError がスローされます。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `needle` は、空の文字列も受け入れるようになりました。
8.0.0 | `encoding` は、nullable になりました。

### 参考

- strripos() - 文字列中で、特定の(大文字小文字を区別しない)文字列が最後に現れた位置を探す
- strrpos() - 文字列中に、ある部分文字列が最後に現れる場所を探す
- mb_strrpos() - 文字列の中に指定した文字列が最後に現れる位置を見つける

# mb_strrpos

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strrpos — 文字列の中に指定した文字列が最後に現れる位置を見つける

### 説明

function 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`
  `haystack` 内の任意の文字数から検索を開始するために指定します。 負の値を指定すると、 `haystack` の末尾より前の任意の地点で検索が停止します。
`encoding`
  `encoding` パラメータには文字エンコーディングを指定します。省略した場合、もしくは `null` の場合は、 内部文字エンコーディングを使用します。

### 戻り値

文字列 `haystack` の中で `needle` が最後に現れる位置を数字で返します。 `needle` が見付からなかった場合、`false` を返します。

### エラー / 例外

- `offset` が `haystack` の長さより大きい場合、 ValueError がスローされます。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `needle` は、空の文字列も受け入れるようになりました。
8.0.0 | 3番目の引数に、`offset` の代わりに `encoding` を渡すことができる仕様は削除されました。
8.0.0 | `encoding` は、nullable になりました。

### 参考

- mb_strpos() - 文字列の中に指定した文字列が最初に現れる位置を見つける
- mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する
- strrpos() - 文字列中に、ある部分文字列が最後に現れる場所を探す

# mb_strstr

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

mb_strstr — 文字列の中で、指定した文字列が最初に現れる位置を見つける

### 説明

function 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`
  `encoding` パラメータには文字エンコーディングを指定します。省略した場合、もしくは `null` の場合は、 内部文字エンコーディングを使用します。

### 戻り値

`haystack` の部分文字列を返します。 `needle` が見つからない場合は `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `needle` は、空の文字列も受け入れるようになりました。
8.0.0 | `encoding` は、nullable になりました。

### 参考

- stristr() - 大文字小文字を区別しない strstr
- strstr() - 文字列が最初に現れる位置を見つける
- mb_stristr() - 大文字小文字を区別せず、 文字列の中で指定した文字列が最初に現れる位置を探す

# mb_strtolower

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_strtolower — 文字列を小文字にする

### 説明

function mb_strtolower(string `$string`, ?string `$encoding` = `null`): string

`string` のすべてのアルファベットを小文字にして返します。

### パラメータ

`string`

  小文字にしたい文字列。

`encoding`
  `encoding` パラメータには文字エンコーディングを指定します。省略した場合、もしくは `null` の場合は、 内部文字エンコーディングを使用します。

### 戻り値

`string` のすべてのアルファベットを小文字にしたものを返します。

### 変更履歴

バージョン | 説明
--- | ---
8.3.0 | ギリシャ文字のシグマ向けに、条件付きのケースルールが実装されました。

### 例

例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 ウムラウト (Ä) を変換することができます。

### 参考

- mb_strtoupper() - 文字列を大文字にする
- mb_convert_case() - 文字列に対してケースフォールディングを行う
- strtolower() - 文字列を小文字にする

# mb_strtoupper

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_strtoupper — 文字列を大文字にする

### 説明

function 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 ウムラウト (ä) を変換することができます。

### 参考

- mb_strtolower() - 文字列を小文字にする
- mb_convert_case() - 文字列に対してケースフォールディングを行う
- strtoupper() - 文字列を大文字にする

# mb_strwidth

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_strwidth — 文字列の幅を返す

### 説明

function 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_substitute_character

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_substitute_character — 置換文字を設定あるいは取得する

### 説明

function 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_substr

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

mb_substr — 文字列の一部を得る

### 説明

function 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.4.0 | 不正な文字列（エンコーディングエラーを含むもの）に対しては、 他のほとんどの mbstring 関数と同じように文字インデックスが解釈されるようになりました。 つまり、mb_strpos() が返す文字インデックスを 直接渡せるようになりました。
8.0.0 | `encoding` は、nullable になりました。

### 参考

- mb_strcut() - 文字列の一部を得る
- mb_internal_encoding() - 内部文字エンコーディングを設定あるいは取得する

# mb_substr_count

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

mb_substr_count — 部分文字列の出現回数を数える

### 説明

function 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() - 副文字列の出現回数を数える

# mb_trim

(PHP 8 >= 8.4.0)

mb_trim — 文字列の先頭および末尾にあるホワイトスペースを取り除く

### 説明

function mb_trim(string `$string`, ?string `$characters` = `null`, ?string `$encoding` = `null`): string

マルチバイト対応の trim() 処理を行い、 `string`の最初および最後から空白文字を取り除き、 取り除かれた文字列を返します。 2番目のパラメータを指定しない場合、 mb_trim() は以下の文字を削除します。

- `" "` (Unicode U+0020)、通常のスペース。
- `"\t"` (Unicode U+0009)、タブ。
- `"\n"` (Unicode U+000A)、改行（ラインフィード）。
- `"\r"` (Unicode U+000D)、キャリッジリターン。
- `"\0"` (Unicode U+0000)、NULバイト。
- `"\v"` (Unicode U+000B)、垂直タブ。
- `"\f"` (Unicode U+000C)、フォームフィード。
- `"\u00A0"` (Unicode U+00A0)、ノーブレークスペース。もしくは、非分割スペース。
- `"\u1680"` (Unicode U+1680)、オガム文字（古代アイルランド語）用のスペース。
- `"\u2000"` (Unicode U+2000)、エンクアッド。アルファベット1文字分の幅を持つスペース。
- `"\u2001"` (Unicode U+2001)、エムクアッド。エンクアッドの2倍の幅を持つスペース。
- `"\u2002"` (Unicode U+2002)、エンスペース。エンクアッドと同じ幅のスペース。
- `"\u2003"` (Unicode U+2003)、エムスペース。エムクアッドと同じ幅のスペース。
- `"\u2004"` (Unicode U+2004)、エムスペースの3分の1の幅を持つスペース。
- `"\u2005"` (Unicode U+2005)、エムスペースの4分の1の幅を持つスペース。
- `"\u2006"` (Unicode U+2006)、エムスペースの6分の1の幅を持つスペース。
- `"\u2007"` (Unicode U+2007)、数字や図の間隔を整えるために使われるスペース。
- `"\u2008"` (Unicode U+2008)、句読点のためにデザインされたスペース。
- `"\u2009"` (Unicode U+2009)、シンスペース。非常に狭いスペース。
- `"\u200A"` (Unicode U+200A)、ヘアスペース。シンスペースよりもさらに細いスペース。
- `"\u2028"` (Unicode U+2028)、ラインセパレーター。行の区切りとして使用。
- `"\u2029"` (Unicode U+2029)、パラグラフセパレーター。段落の区切りとして使用。
- `"\u202F"` (Unicode U+202F)、ナローノーブレークスペース。通常の非分割スペースよりも狭く、ラテン文字や句読点の間で使用。
- `"\u205F"` (Unicode U+205F)、数式などで使われるスペース。
- `"\u3000"` (Unicode U+3000)、全角文字用のスペース。
- `"\u0085"` (Unicode U+0085)、次行（NEL）。
- `"\u180E"` (Unicode U+180E)、モンゴル語のテキスト内で母音を区切るために使用されるスペース。

### パラメータ

`string`
  ホワイトスペースを取り除くstring。
`characters`
  `characters` パラメータにより、 削除する文字を指定することも可能です。 削除したい全ての文字をリストにしてください。
`encoding`
  `encoding` パラメータには文字エンコーディングを指定します。省略した場合、もしくは `null` の場合は、 内部文字エンコーディングを使用します。

### 戻り値

トリム処理を行った文字列を返します。

### 参考

- mb_ltrim() - 文字列の先頭にあるホワイトスペースを取り除く
- mb_rtrim() - 文字列の末尾にあるホワイトスペースを取り除く
- trim() - 文字列の先頭および末尾にあるホワイトスペースを取り除く

# mb_ucfirst

(PHP 8 >= 8.4.0)

mb_ucfirst — 文字列の最初の文字を大文字にする

### 説明

function mb_ucfirst(string `$string`, ?string `$encoding` = `null`): string

マルチバイト対応の ucfirst() 処理を行い、 `string` の最初の文字をタイトルケースに変換して返します。

### パラメータ

`string`
  入力文字列。
`encoding`
  文字エンコーディングを指定します。省略した場合、もしくはnullの場合は、内部文字エンコーディングを使用します。

### 戻り値

変換後の文字列を返します。

### 注意

> 注意:

> strtolower() や strtoupper()のような関数とは対照的に、 ケースフォールディングはUnicode 文字属性を基準に行われます。 したがって、この挙動はロケールの設定に影響されず、また、すべてのアルファベット、 例えば a ウムラウト (ä)などを変換することができます。

Unicodeプロパティについての詳細はこちらを参照してください» http://www.unicode.org/reports/tr21/。

### 参考

- mb_lcfirst() - 文字列の最初の文字を小文字にする
- mb_convert_case() - 文字列に対してケースフォールディングを行う
- ucfirst() - 文字列の最初の文字を大文字にする

## 目次

- 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_lcfirst — 文字列の最初の文字を小文字にする
- mb_list_encodings — サポートするすべてのエンコーディングの配列を返す
- mb_ltrim — 文字列の先頭にあるホワイトスペースを取り除く
- 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_rtrim — 文字列の末尾にあるホワイトスペースを取り除く
- 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_trim — 文字列の先頭および末尾にあるホワイトスペースを取り除く
- mb_ucfirst — 文字列の最初の文字を大文字にする

- インストール/設定
  - インストール手順
  - 実行時設定
- 定義済み定数
- サポートされるエンコーディングの概要
- 日本語のマルチバイト文字に関する基本事項
- 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_lcfirst — 文字列の最初の文字を小文字にする
  - mb_list_encodings — サポートするすべてのエンコーディングの配列を返す
  - mb_ltrim — 文字列の先頭にあるホワイトスペースを取り除く
  - 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_rtrim — 文字列の末尾にあるホワイトスペースを取り除く
  - 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_trim — 文字列の先頭および末尾にあるホワイトスペースを取り除く
  - mb_ucfirst — 文字列の最初の文字を大文字にする

# Pspell

# はじめに

警告

この拡張モジュールは、PHP 8.4.0 以降では非推奨となり、PHP にもバンドルされません。

これらの関数により、単語のスペルチェックを行い、修正案を提案させる ことが可能となります。

# インストール/設定

## 目次

- 要件
- インストール手順
- リソース型

## 要件

PHP を pspell サポートつきでコンパイルするには、aspellライブラリが 必要です。これは、» http://aspell.net/ で取得可能です。

## インストール手順

## PHP 8.4

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 8.4.0

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/pspell.

## PHP < 8.4

この拡張モジュールを有効にするには、--with-pspell[=dir] オプションを指定して PHP をコンパイルします。

> 注意: 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

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_add_to_personal — ユーザーの単語リストに単語を追加する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_session

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_add_to_session — 現在のセッションの単語リストに単語を追加する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

# pspell_check

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_check — 単語をチェックする

### 説明

function pspell_check(PSpell\Dictionary `$dictionary`, string `$word`): bool

pspell_check() は単語のスペルをチェックします。

### パラメータ

`dictionary`
  PSpell\Dictionary クラスのインスタンス。
`word`

  チェックする単語。

### 戻り値

スペルが正しい場合に `true`、そうでない場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | 引数 `dictionary` は、PSpell\Dictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_clear_session

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_clear_session — 現在のセッションをクリアする

### 説明

function pspell_clear_session(PSpell\Dictionary `$dictionary`): bool

pspell_clear_session() は、 現在のセッションをクリアします。現在の単語リストはブランクになり、 例えば pspell_save_wordlist() でこのリストを保存しても何もおきません。

### パラメータ

`dictionary`
  PSpell\Dictionary クラスのインスタンス。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | 引数 `dictionary` は、PSpell\Dictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_config_create

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_create — 辞書をオープンする際に使用する設定を作成する

### 説明

function 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 クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。

### 例

例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_data_dir

(PHP 5, PHP 7, PHP 8)

pspell_config_data_dir — 言語のデータファイルの場所

### 説明

function pspell_config_data_dir(PSpell\Config `$config`, string `$directory`): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | 引数 `config` は、PSpell\Config クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

# pspell_config_dict_dir

(PHP 5, PHP 7, PHP 8)

pspell_config_dict_dir — メイン単語リストの場所

### 説明

function pspell_config_dict_dir(PSpell\Config `$config`, string `$directory`): bool

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | 引数 `config` は、PSpell\Config クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

# pspell_config_ignore

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_ignore — 長さが N 文字未満の単語を無視する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_mode

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_mode — 返される提案の数のモードを変更する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_personal — 個人の単語リストを保持するファイルを設定する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_repl

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_repl — 置換候補を保持するファイルを設定する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_runtogether

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_runtogether — 複合語を有効な単語の組み合わせとして考慮する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_save_repl

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_config_save_repl — 単語リストと共に置換リストを保存するかどうかを定義する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 注意

> 注意:

> この関数は、pspell .11.2およびaspell .32.5 以降を有していない場合には 動作しないことに注意してください。

# pspell_new

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new — 新規辞書をロードする

### 説明

function 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 クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。

### 例

例1 pspell_new()

    <?php
    $pspell = pspell_new("en", "", "", "",
                         (PSPELL_FAST|PSPELL_RUN_TOGETHER));
    ?>

# pspell_new_config

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new_config — 指定した設定に基づき新規辞書をロードする

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。
8.1.0 | PSpell\Dictionary クラスのインスタンスを返すようになりました。 これより前のバージョンでは、resource を返していました。

### 例

例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_personal

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_new_personal — 個人の単語リストを有する新規辞書をロードする

### 説明

function 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 クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。

### 例

例1 pspell_new_personal()

    <?php
    $pspell = pspell_new_personal ("/var/dictionaries/custom.pws",
            "en", "", "", "", PSPELL_FAST|PSPELL_RUN_TOGETHER);
    ?>

# pspell_save_wordlist

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_save_wordlist — 個人の単語リストをファイルに保存する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_store_replacement

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_store_replacement — 単語を置換する組を保存する

### 説明

function 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 クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_suggest

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

pspell_suggest — 単語のスペルについて修正候補を示す

### 説明

function pspell_suggest(PSpell\Dictionary `$dictionary`, string `$word`): array|false

pspell_suggest() は、 指定した単語について可能性のあるスペルの配列を返します。

### パラメータ

`dictionary`
  PSpell\Dictionary クラスのインスタンス。
`word`

  調べたい単語。

### 戻り値

修正候補の配列を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | 引数 `dictionary` は、PSpell\Dictionary クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、resource を期待していました。

### 例

例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_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 クラス

(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 {
}

- インストール/設定
  - 要件
  - インストール手順
  - リソース型
- 定義済み定数
- 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 クラス

# GNU Recode

# はじめに

警告

この拡張モジュールは、メンテナンスされていません。

このモジュールは、GNU recode ライブラリへのインターフェイスを 有しています。GNU Recode ライブラリは、様々にコード化された 文字や表面的なエンコード法を相互に変換します。 正確に変換できない場合、問題のある文字を削除するか近似を行います。 このライブラリは、約 150 種類の文字セットを認識、生成することが可能で、 ほとんど全ての組み合わせで相互の変換を行うことができます。 » RFC 1345 文字セットの ほとんどがサポートされています。

> 注意: PHp 7.4.0 以降、この拡張モジュールは PHP 本体にバンドルされなくなり、 » PECL に移動しました。 代わりに、マルチバイト文字列 または iconv 拡張モジュールの利用を検討してください。

> 注意: この拡張モジュールは Windows 環境では利用できません。

# インストール/設定

## 目次

- 要件
- インストール手順

## 要件

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

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode — recode_string() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 recode_string().

# recode_file

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode_file — コード変換指令に基づきファイルからファイルにコード変換する

### 説明

function 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_string

(PHP 4, PHP 5, PHP 7 < 7.4.0)

recode_string — コード変換指令に基づき文字列のコードを変換する

### 説明

function 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: á");
    ?>

### 注意

簡単なコード変換指令は、"lat1..iso646-de" のようになります。

### 参考

- コード変換指令に関する詳細な手順に関しては、インストールされている GNU Recode のドキュメントも参照ください。
- mb_convert_encoding() - ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する
- UConverter::transcode() - ある文字エンコーディングから別の文字エンコーディングに文字列を変換する
- iconv() - ある文字エンコーディングの文字列を、別の文字エンコーディングに変換する

## 目次

- recode — recode_string のエイリアス
- recode_file — コード変換指令に基づきファイルからファイルにコード変換する
- recode_string — コード変換指令に基づき文字列のコードを変換する

- インストール/設定
  - 要件
  - インストール手順
- Recode 関数
  - recode — recode_string のエイリアス
  - recode_file — コード変換指令に基づきファイルからファイルにコード変換する
  - recode_string — コード変換指令に基づき文字列のコードを変換する

- 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 関数

# 画像処理および作成

# Exchangeable image information

# はじめに

exif 拡張モジュールを使用すると、画像のメタデータを扱うことが可能と なります。例えば、デジタルカメラで撮影した画像ファイルから 画像のヘッダ情報を読み込むために exif 関数を使用することができます。 こうした情報は、通常 JPEG や TIFF 画像で見つかります。

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定

## 要件

`--enable-exif` オプションを用いて PHP をコンパイルする必要があります。 EXIF タグでマルチバイトのサポートを有効にするには、 `--enable-mbstring` を用いてPHPをコンパイルすることで、 mbstring 拡張モジュールを有効にしなければいけません。 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

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

exif_imagetype — 画像の種類を判別する

### 説明

function 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`
20 | `IMAGETYPE_HEIF`

> 注意: 画像の形式を判別するために必要なだけのバイト数を読み込めない場合、 exif_imagetype() は `E_NOTICE` を発行して `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
7.1.0 | WebP をサポートしました
8.1.0 | AVIF をサポートしました。
8.5.0 | HEIF をサポートしました。

### 例

例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_read_data

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_read_data — 画像ファイルから EXIF ヘッダを読み込む

### 説明

function 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 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_tagname

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_tagname — インデックスに対応するヘッダ名を取得する

### 説明

function 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_thumbnail

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

exif_thumbnail — 画像に埋め込まれたサムネイルを取得する

### 説明

function 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タイプを取得する

# 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 | この関数エイリアスは非推奨になりました。

## 目次

- exif_imagetype — 画像の種類を判別する
- exif_read_data — 画像ファイルから EXIF ヘッダを読み込む
- exif_tagname — インデックスに対応するヘッダ名を取得する
- exif_thumbnail — 画像に埋め込まれたサムネイルを取得する
- read_exif_data — exif_read_data のエイリアス

- インストール/設定
  - 要件
  - インストール手順
  - 実行時設定
- 定義済み定数
- Exif 関数
  - exif_imagetype — 画像の種類を判別する
  - exif_read_data — 画像ファイルから EXIF ヘッダを読み込む
  - exif_tagname — インデックスに対応するヘッダ名を取得する
  - exif_thumbnail — 画像に埋め込まれたサムネイルを取得する
  - read_exif_data — exif_read_data のエイリアス

# 画像処理 (GD)

# はじめに

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() 関数を使いましょう。 コンパイル時の設定については、インストール方法のページを参照ください。

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定
- リソース型

## 要件

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_HEIF` (int)
  画像タイプ定数。image_type_to_mime_type() や image_type_to_extension() 関数で使用します。 (PHP 8.5.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);

    ?>

この例のスクリプトは、`<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);
    ?>

この例は、すかしやスタンプを写真あるいは著作権つき画像に追加するための一般的な方法です。 スタンプ画像内のアルファチャネルのテキストはアンチエイリアス処理されることに注意しましょう。 画像をコピーしてもこれは残り続けます。

## 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');

    ?>

この例は、imagecopymerge() を使ってスタンプを元画像にかぶせます。 これを使うと、スタンプの不透明度を設定することができます。 今回の例では 50% の不透明度に設定しています。 この半透明のすかしを用いる方法は、著作権つきの画像を保護するのに便利です。 すかしをとるのは非常に難しく、またもとの画像の見栄えも損ねません。

# GD および Image 関数

# gd_info

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

gd_info — 現在インストールされているGDライブラリに関する情報を取得する

### 説明

function 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 がサポートしている画像形式を返す

# getimagesize

(PHP 4, PHP 5, PHP 7, PHP 8)

getimagesize — 画像の大きさを取得する

### 説明

function 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() が返す幅と高さはいずれもゼロとなります。

> 注意: getimagesize() は、どの画像のメタデータにも依存しません。 たとえば、Exif の `Orientation` フラグが、 画像を90度か270度回転するよう設定されていた場合、 0番目と1番目の要素は入れ替えられます。 つまり、これらは高さと幅をそれぞれ含んでいるということです。

2 番目の要素は `IMAGETYPE_*` 定数のひとつで、 画像の形式を表します。

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` レベルのエラーを発生させます。

PHP 8.0.0 以降、`filename` が空の場合に ValueError がスローされます。

### 変更履歴

バージョン | 説明
--- | ---
8.2.0 | AVIF 画像の ビット数、チャンネル情報、幅と高さの情報(dimensions) を返すようになりました。 これより前のバージョンでは、幅と高さの情報は `0x0` として報告され、ビット数とチャンネル情報は全く報告されていませんでした。
8.0.0 | `filename` が空の場合に ValueError がスローされるようになりました。 これより前のバージョンでは、`E_WARNING` が発生し、関数は `false` を返していました。
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() - 画像の高さを取得する

# getimagesizefromstring

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

getimagesizefromstring — 画像の大きさを文字列から取得する

### 説明

function 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() - 画像の大きさを取得する

# image_type_to_extension

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

image_type_to_extension — 画像形式からファイルの拡張子を取得する

### 説明

function image_type_to_extension(int `$image_type`, bool `$include_dot` = `true`): string|false

指定した定数 `IMAGETYPE_*` に対応する拡張子を返します。

### パラメータ

`image_type`

  `IMAGETYPE_*` 定数のいずれかひとつ。

`include_dot`

  拡張子の前にドットをつけるかどうか。デフォルトは `true`。

### 戻り値

指定した型に対応する拡張子を文字列で返します。 失敗した場合に `false` を返します

### 例

例1 image_type_to_extension() の例

    <?php
    // 画像のインスタンスを作成します
    $im = imagecreatetruecolor(100, 100);

    // 画像を保存します
    imagepng($im, './test' . image_type_to_extension(IMAGETYPE_PNG));
    ?>

### 注意

> 注意: この関数は、GD 画像ライブラリは必要ありません。

# 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タイプを取得する

### 説明

function image_type_to_mime_type(int `$image_type`): string

image_type_to_mime_type() は IMAGETYPE 定数で指定される Mime-Type を取得します。

### パラメータ

`image_type`

  `IMAGETYPE_*` 定数のいずれか。

### 戻り値

戻り値は次のとおりです。

戻り値の定数
`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`
`IMAGETYPE_HEIF` | `image/heif`

### 例

例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() - 画像に埋め込まれたサムネイルを取得する

# image2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

image2wbmp — 画像をブラウザあるいはファイルに出力する

警告

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

### 説明

function 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); // ストリームを直接出力します。
    ?>

### 参考

- imagewbmp() - 画像をブラウザあるいはファイルに出力する

# imageaffine

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffine — 元の画像を、オプションのクリッピング領域を使ってアフィン変換した画像を返す

### 説明

function 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 が返されていました。

# imageaffinematrixconcat

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffinematrixconcat — 二つのアフィン変換行列を連結する

### 説明

function 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() - アフィン変換行列を取得する

# imageaffinematrixget

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageaffinematrixget — アフィン変換行列を取得する

### 説明

function 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() - 二つのアフィン変換行列を連結する

# imagealphablending

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagealphablending — イメージのブレンドモードを設定する

### 説明

function imagealphablending(GdImage `$image`, bool `$enable`): true

imagealphablending() によりTrueColorイメージに 二つの異なる描画モードを使用可能となります。ブレンドモードでは、 全ての描画関数に指定される色のalphaチャネル要素として使用され、 例えばimagesetpixel()では背景色の透過割合を定 義します。結果として、gd は描画色に関してその点に存在する色を自動 的にブレンドし、イメージに結果を保存します。結果のピクセルは、透 明になります。ブレンドモードでない場合、描画色は形式的にそのアル ファチャネル情報にコピーされ、出力ピクセルを置換します。ブレンド モードは、パレットイメージを描画している際には使用できません。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`enable`

  ブレンドモードを有効にするかどうか。True Color 画像の場合のデフォルトは `true`、それ以外の場合のデフォルトは `false` です。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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);
    ?>

# imageantialias

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imageantialias — アンチエイリアス機能を使用すべきかどうかを判断する

### 説明

function imageantialias(GdImage `$image`, bool `$enable`): true

直線や多角形を高速に描画するためのアンチエイリアス機能を有効にします。 アルファコンポーネントはサポートしていません。ダイレクトブレンド操作を 使用します。truecolor 画像に対してのみ動作します。

thickness および styled はサポートしていません。

背景色が透明な場合にアンチエイリアス機能を使用すると、予期せぬ結果に 終わることがあります。ブレンドメソッドでは、背景色が使用されます。 アルファコンポーネントをサポートしていないため、アルファコンポーネントに 基づいたアンチエイリアス手法は使用できません。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`enable`

  アンチエイリアスを有効にするかどうか。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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);
    ?>

上の例の出力は、 たとえば以下のようになります。

### 参考

- imagecreatetruecolor() - TrueColor イメージを新規に作成する

# imagearc

(PHP 4, PHP 5, PHP 7, PHP 8)

imagearc — 部分楕円を描画する

### 説明

function imagearc(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$start_angle`,
int `$end_angle`,
int `$color`
): true

imagearc() は、指定した座標を中心とする円弧を描画します。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`center_x`

  中心の x 座標。

`center_y`

  中心の y 座標。

`width`

  円弧の幅。

`height`

  円弧の高さ。

`start_angle`

  始点の角度。

`end_angle`

  終点の角度。 0° は 3 時の位置で、そこから時計回りの方向に円弧が描かれます。

`color`

  imagecolorallocate() で作成された色識別子。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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);

    ?>

上の例の出力は、 たとえば以下のようになります。

### 参考

- imagefilledarc() - 楕円弧を描画し、塗りつぶす
- imageellipse() - 楕円を描画する
- imagefilledellipse() - 塗りつぶされた楕円を描画する

# imageavif

(PHP 8 >= 8.1.0)

imageavif — 画像をブラウザあるいはファイルに出力する

### 説明

function 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` を指定した場合、 デフォルト値 `52` を使います。

`speed`

  `speed` はオプションで、 0 (ゆっくり、小さなファイル) から 10 (速い、大きなファイル) までの値を取ります。 `-1` を指定した場合、 デフォルト値 `6` を使います。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は `true` を返します。

### エラー / 例外

`quality` または、`speed` が不正の場合、 ValueError をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `quality` または、`speed` が不正の場合、 ValueError をスローするようになりました。

### 参考

- imagepng() - PNG イメージをブラウザまたはファイルに出力する
- imagewbmp() - 画像をブラウザあるいはファイルに出力する
- imagejpeg() - 画像をブラウザあるいはファイルに出力する
- imagetypes() - この PHP がサポートしている画像形式を返す

# imagebmp

(PHP 7 >= 7.2.0, PHP 8)

imagebmp — ビットマップ画像をブラウザかファイルに出力する

### 説明

function 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');

    ?>

# imagechar

(PHP 4, PHP 5, PHP 7, PHP 8)

imagechar — 水平に文字を描画する

### 説明

function imagechar(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$char`,
int `$color`
): true

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` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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);

    ?>

上の例の出力は、 たとえば以下のようになります。

### 参考

- imagecharup() - 垂直に文字を描画する
- imageloadfont() - 新しいフォントを読み込む

# imagecharup

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecharup — 垂直に文字を描画する

### 説明

function imagecharup(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$char`,
int `$color`
): true

指定した画像 `image` の指定した位置に、 文字 `char` を垂直に描画します。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`font`
  latin2 エンコーディングの組み込みのフォントの場合は 1, 2, 3, 4, 5 のいずれか (数字が大きなほうが、より大きいフォントに対応します)、あるいは imageloadfont() が返した、GdFont クラスのインスタンスのいずれか。
`x`

  始点の x 座標。

`y`

  始点の y 座標。

`char`

  描画する文字。

`color`

  imagecolorallocate() で作成された色識別子。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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);

    ?>

上の例の出力は、 たとえば以下のようになります。

### 参考

- imagechar() - 水平に文字を描画する
- imageloadfont() - 新しいフォントを読み込む

# imagecolorallocate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorallocate — 画像で使用する色を作成する

### 説明

function 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() - イメージの色リソースを開放する

# imagecolorallocatealpha

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imagecolorallocatealpha — 画像で使用する色を透過度を指定して作成する

### 説明

function 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);
    ?>

上の例の出力は、 たとえば以下のようになります。

例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() - イメージの色リソースを開放する

# imagecolorat

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorat — ピクセルの色のインデックスを取得する

### 説明

function 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() - 点を生成する

# imagecolorclosest

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorclosest — 指定した色に最も近い色のインデックスを取得する

### 説明

function 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";
    }
    ?>

上の例の出力は、 たとえば以下のようになります。

    #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() - 色合い、白、黒を有する色のインデックスを得る

# imagecolorclosestalpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorclosestalpha — 指定した色+アルファ値に最も近い色のインデックスを取得する

### 説明

function 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";
    }
    ?>

上の例の出力は、 たとえば以下のようになります。

    #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() - 色合い、白、黒を有する色のインデックスを得る

# imagecolorclosesthwb

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecolorclosesthwb — 色合い、白、黒を有する色のインデックスを得る

### 説明

function 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);
    ?>

上の例の出力は、 たとえば以下のようになります。

    HWB: 33

### 参考

- imagecolorclosest() - 指定した色に最も近い色のインデックスを取得する

# imagecolordeallocate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolordeallocate — イメージの色リソースを開放する

### 説明

function imagecolordeallocate(GdImage `$image`, int `$color`): true

imagecolorallocate() または imagecolorallocatealpha() で確保された色を開放します。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`color`

  色 ID。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `image` は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な `gd` resource が期待されていました。

### 例

例1 imagecolordeallocate() の使用法

    <?php
    $white = imagecolorallocate($im, 255, 255, 255);
    imagecolordeallocate($im, $white);
    ?>

### 参考

- imagecolorallocate() - 画像で使用する色を作成する
- imagecolorallocatealpha() - 画像で使用する色を透過度を指定して作成する

# imagecolorexact

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorexact — 指定した色のインデックスを取得する

### 説明

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

    ?>

上の例の出力は、 たとえば以下のようになります。

    Array
    (
        [0] => 16711680
        [1] => 0
        [2] => 16777215
        [3] => 6618932
    )

### 参考

- imagecolorclosest() - 指定した色に最も近い色のインデックスを取得する

# imagecolorexactalpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorexactalpha — 指定した色+アルファ値のインデックスを取得する

### 説明

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

    ?>

上の例の出力は、 たとえば以下のようになります。

    Array
    (
        [0] => 16711680
        [1] => 2130706432
        [2] => 939524095
        [3] => 342163252
    )

### 参考

- imagecolorclosestalpha() - 指定した色+アルファ値に最も近い色のインデックスを取得する

# imagecolormatch

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagecolormatch — パレットイメージの色を True カラーイメージに近づける

### 説明

function imagecolormatch(GdImage `$image1`, GdImage `$image2`): true

パレットイメージの色を True カラーイメージに近づけます。

### パラメータ

`image1`

  truecolor イメージオブジェクト

`image2`

  パレットイメージオブジェクト。 `image1` と同じ大きさの画像を指します。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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);
    ?>

### 参考

- imagecreatetruecolor() - TrueColor イメージを新規に作成する

# imagecolorresolve

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorresolve — 指定した色または出来るだけ近い色のインデックスを得る

### 説明

function 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);
    ?>

上の例の出力は、 たとえば以下のようになります。

    Array
    (
        [0] => 89
        [1] => 85
    )

### 参考

- imagecolorclosest() - 指定した色に最も近い色のインデックスを取得する

# imagecolorresolvealpha

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecolorresolvealpha — 指定した色+アルファ値または最も近い色のインデックスを取得する

### 説明

function 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);
    ?>

上の例の出力は、 たとえば以下のようになります。

    Array
    (
        [0] => 89
        [1] => 85
    )

### 参考

- imagecolorclosestalpha() - 指定した色+アルファ値に最も近い色のインデックスを取得する

# imagecolorset

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorset — 指定したパレットインデックスの色を設定する

### 説明

function 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);
    ?>

### 参考

- imagecolorat() - ピクセルの色のインデックスを取得する

# imagecolorsforindex

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorsforindex — カラーインデックスからカラーを取得する

### 説明

function 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() - 指定した色のインデックスを取得する

# imagecolorstotal

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolorstotal — 画像パレットの色数を検出する

### 説明

function 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);
    ?>

上の例の出力は、 たとえば以下のようになります。

    色の総数: 128

### 参考

- imagecolorat() - ピクセルの色のインデックスを取得する
- imagecolorsforindex() - カラーインデックスからカラーを取得する
- imageistruecolor() - 画像が truecolor かどうか調べる

# imagecolortransparent

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecolortransparent — 透明色を定義する

### 説明

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

上の例の出力は、 たとえば以下のようになります。

### 注意

> 注意: 透過性は imagecopymerge() かつ True カラーの場合のみコピーされます。imagecopy() もしくはパレットイメージの場合はコピーされません。

> 注意:

> 透明色は画像のプロパティであり、色のプロパティではありません。 ある色を透明色と定義したら、画像上で既にその色で着色されてる領域も 透明になります。

# imageconvolution

(PHP 5 >= 5.1.0, PHP 7, PHP 8)

imageconvolution — div および offset の係数を使用し、3x3 の畳み込み配列を適用する

### 説明

function 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);
    ?>

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

例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() - 画像にフィルタを適用する

# imagecopy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecopy — 画像の一部をコピーする

### 説明

function 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`
): true

`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` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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);
    ?>

上の例の出力は、 たとえば以下のようになります。

### 参考

- imagecrop() - 指定した矩形に画像をクロップする

# imagecopymerge

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecopymerge — イメージの一部をコピー、マージする

### 説明

function 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`
): true

`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` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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);
    ?>

# imagecopymergegray

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecopymergegray — グレースケールでイメージの一部をコピー、マージする

### 説明

function 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`
): true

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` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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);
    ?>

# imagecopyresampled

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecopyresampled — 再サンプリングを行いイメージの一部をコピー、伸縮する

### 説明

function 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`
): true

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` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | 戻り値の型が、`true` になりました。これより前のバージョンでは、bool でした。
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() - 指定した矩形に画像をクロップする

# imagecopyresized

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecopyresized — 画像の一部をコピーしサイズを変更する

### 説明

function 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`
): true

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` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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() - 指定した矩形に画像をクロップする

# imagecreate

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreate — パレットを使用する新規画像を作成する

### 説明

function 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);
    ?>

上の例の出力は、 たとえば以下のようになります。

### 参考

- imagecreatetruecolor() - TrueColor イメージを新規に作成する

# imagecreatefromavif

(PHP 8 >= 8.1.0)

imagecreatefromavif — 新しい画像をファイルあるいは URL から作成する

### 説明

function imagecreatefromavif(string `$filename`): GdImage|false

imagecreatefromavif() は、 指定されたファイルから取得した画像を表す、 画像オブジェクトを返します。

### パラメータ

`filename`

  AVIF ラスタ画像へのパス。

### 戻り値

成功した場合に画像オブジェクト、エラー時に `false` を返します。

# imagecreatefrombmp

(PHP 7 >= 7.2.0, PHP 8)

imagecreatefrombmp — 新しい画像をファイルあるいは URL から作成する

### 説明

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

# imagecreatefromgd

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd — GD ファイルまたは URL から新規イメージを生成する

### 説明

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

### 注意

警告

GD と GD2 画像フォーマットは libgd が作った独自仕様の画像フォーマットです。これらは obsolete と見なされているため、開発とテストの用途にだけ使うべきです。

# imagecreatefromgd2

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd2 — GD2 ファイルまたは URL から新規イメージを生成する

### 説明

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

### 注意

警告

GD と GD2 画像フォーマットは libgd が作った独自仕様の画像フォーマットです。これらは obsolete と見なされているため、開発とテストの用途にだけ使うべきです。

# imagecreatefromgd2part

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagecreatefromgd2part — GD2 ファイルまたは URL の指定した部分から新規イメージを生成する

### 説明

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

### 注意

警告

GD と GD2 画像フォーマットは libgd が作った独自仕様の画像フォーマットです。これらは obsolete と見なされているため、開発とテストの用途にだけ使うべきです。

# imagecreatefromgif

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefromgif — 新しい画像をファイルあるいは URL から作成する

### 説明

function 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);
    ?>

上の例の出力は、 たとえば以下のようになります。

# imagecreatefromjpeg

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefromjpeg — 新しい画像をファイルあるいは URL から作成する

### 説明

function 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);
    ?>

上の例の出力は、 たとえば以下のようになります。

# imagecreatefrompng

(PHP 4, PHP 5, PHP 7, PHP 8)

imagecreatefrompng — 新しい画像をファイルあるいは URL から作成する

### 説明

function 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);
    ?>

上の例の出力は、 たとえば以下のようになります。

# imagecreatefromstring

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

imagecreatefromstring — 文字列の中のイメージストリームから新規イメージを作成する

### 説明

function 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);
    }
    else {
        echo 'エラーが発生しました。';
    }
    ?>

上の例の出力は、 たとえば以下のようになります。

### 参考

- imagecreatefromjpeg() - 新しい画像をファイルあるいは URL から作成する
- imagecreatefrompng() - 新しい画像をファイルあるいは URL から作成する
- imagecreatefromgif() - 新しい画像をファイルあるいは URL から作成する
- imagecreatetruecolor() - TrueColor イメージを新規に作成する

# imagecreatefromtga

(PHP 7 >= 7.4.0, PHP 8)

imagecreatefromtga — 新しい画像をファイルあるいは URL から作成する

### 説明

function imagecreatefromtga(string `$filename`): GdImage|false

imagecreatefromtga() は 指定されたファイルから、画像オブジェクトを返します。

### パラメータ

`filename`

  Truevision TGA 画像ファイルへのパス。

### 戻り値

成功した場合に画像オブジェクト、エラー時に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | 成功時に、この関数は GdImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。

# imagecreatefromwbmp

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromwbmp — 新しい画像をファイルあるいは URL から作成する

### 説明

function 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);
    ?>

# imagecreatefromwebp

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

imagecreatefromwebp — 新しい画像をファイルあるいは URL から作成する

### 説明

function 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);
    ?>

# imagecreatefromxbm

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromxbm — 新しい画像をファイルあるいは URL から作成する

### 説明

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

# imagecreatefromxpm

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagecreatefromxpm — 新しい画像をファイルあるいは URL から作成する

### 説明

function 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);
    ?>

# imagecreatetruecolor

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagecreatetruecolor — TrueColor イメージを新規に作成する

### 説明

function 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);
    ?>

上の例の出力は、 たとえば以下のようになります。

### 参考

- imagecreate() - パレットを使用する新規画像を作成する

# imagecrop

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagecrop — 指定した矩形に画像をクロップする

### 説明

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

### 参考

- imagecropauto() - 利用可能なモードを指定して、画像を自動的にクロップする

# imagecropauto

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagecropauto — 利用可能なモードを指定して、画像を自動的にクロップする

### 説明

function 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) { // 新しい画像オブジェクトが戻された場合にだけ
        $im = $cropped;       // クロップ後の画像を $im に代入します
    }
    ?>

### 参考

- imagecrop() - 指定した矩形に画像をクロップする

# imagedashedline

(PHP 4, PHP 5, PHP 7, PHP 8)

imagedashedline — 破線を描画する

### 説明

function imagedashedline(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

これは古い関数です。代わりに imagesetstyle() と imageline() の組み合せを使用してください。0, 0 は画像の左上の角です。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`x1`

  1 つ目の点の x 座標。

`y1`

  1 つ目の点の y 座標。

`x2`

  2 つ目の点の x 座標。

`y2`

  2 つ目の点の y 座標。

`color`

  塗りつぶし色。imagecolorallocate() で作成された色識別子。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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');
    ?>

上の例の出力は、 たとえば以下のようになります。

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

### 参考

- imagesetstyle() - 線描画用のスタイルを設定する
- imageline() - 直線を描画する

# imagedestroy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagedestroy — 画像を破棄する

警告

この関数は PHP 8.5.0 で 非推奨になります。この関数に頼らないことを強く推奨します。

### 説明

#[\Deprecated]
function imagedestroy(GdImage `$image`): true

> 注意: この関数を実行しても何も起こりません。PHP 8.0.0 より前のバージョンでは、この関数はリソースを閉じるのに使われていました。

PHP 8.0.0 より前のバージョンでは、 imagedestroy() は画像 `image` を保持するメモリを解放していました。 PHP 8.0.0 以降のバージョンでは、 GD 拡張モジュールはリソースの代わりにオブジェクトを使うようになったので、 オブジェクトは明示的にクローズできなくなっています。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.5.0 | この関数は推奨されなくなりました。
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);
    ?>

# imageellipse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imageellipse — 楕円を描画する

### 説明

function imageellipse(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$color`
): true

指定した座標を中心とする楕円を描画します。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`center_x`

  中心の x 座標。

`center_y`

  中心の y 座標。

`width`

  楕円の幅。

`height`

  楕円の高さ。

`color`

  楕円の色。imagecolorallocate() で作成された色識別子。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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() は imagesetthickness() を無視します。

### 参考

- imagefilledellipse() - 塗りつぶされた楕円を描画する
- imagearc() - 部分楕円を描画する

# imagefill

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefill — 塗り潰す

### 説明

function imagefill(
GdImage `$image`,
int `$x`,
int `$y`,
int `$color`
): true

指定した座標 (左上が 0, 0 です) から、指定した色 `color` で `image` を塗りつぶします。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`x`

  開始位置の x 座標。

`y`

  開始位置の y 座標。

`color`

  塗りつぶし色。imagecolorallocate() で作成された色識別子。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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);
    ?>

上の例の出力は、 たとえば以下のようになります。

### 参考

- imagecolorallocate() - 画像で使用する色を作成する

# imagefilledarc

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagefilledarc — 楕円弧を描画し、塗りつぶす

### 説明

function imagefilledarc(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$start_angle`,
int `$end_angle`,
int `$color`,
int `$style`
): true

指定した `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` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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);
    ?>

上の例の出力は、 たとえば以下のようになります。

# imagefilledellipse

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagefilledellipse — 塗りつぶされた楕円を描画する

### 説明

function imagefilledellipse(
GdImage `$image`,
int `$center_x`,
int `$center_y`,
int `$width`,
int `$height`,
int `$color`
): true

指定した `image` の指定した座標を中心として楕円を描画します。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`center_x`

  中心の x 座標。

`center_y`

  中心の y 座標。

`width`

  楕円の幅。

`height`

  楕円の高さ。

`color`

  塗りつぶし色。imagecolorallocate() で作成された色識別子。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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() は imagesetthickness() を無視します。

### 参考

- imageellipse() - 楕円を描画する
- imagefilledarc() - 楕円弧を描画し、塗りつぶす

# imagefilledpolygon

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilledpolygon — 塗りつぶした多角形を描画する

### 説明

PHP 8.0.0 以降のシグネチャ(名前付き引数をサポートしていません)

function imagefilledpolygon(GdImage `$image`, array `$points`, int `$color`): bool

代替のシグネチャ (PHP 8.1.0 以降 は非推奨)

function 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);
    ?>

上の例の出力は、 たとえば以下のようになります。

### 参考

- imagepolygon() - 多角形を描画する

# imagefilledrectangle

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilledrectangle — 塗りつぶした矩形を描画する

### 説明

function imagefilledrectangle(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

色 `color` で塗りつぶした矩形を、 指定した `image` 上に作成します。 開始位置と終了位置を指定します。0, 0 が画像の左上角を表します。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`x1`

  開始位置の x 座標。

`y1`

  開始位置の y 座標。

`x2`

  終了位置の x 座標。

`y2`

  終了位置の y 座標。

`color`

  塗りつぶし色。imagecolorallocate() で作成された色識別子。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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');
    ?>

上の例の出力は、 たとえば以下のようになります。

# imagefilltoborder

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefilltoborder — 特定色で塗りつぶす

### 説明

function imagefilltoborder(
GdImage `$image`,
int `$x`,
int `$y`,
int `$border_color`,
int `$color`
): true

imagefilltoborder()は、 `border_color`で指定した色を境界色として塗りつぶし を行います。(`x`,`y`)が 塗りつぶしの始点(左上が0, 0)で、領域内を `color`色で塗りつぶします。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`x`

  開始位置の x 座標。

`y`

  開始位置の y 座標。

`border_color`

  境界色。imagecolorallocate() で作成された色識別子。

`color`

  塗りつぶし色。imagecolorallocate() で作成された色識別子。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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);
    ?>

上の例の出力は、 たとえば以下のようになります。

### 注意

塗りつぶしのアルゴリズムは、 どのピクセルが既に設定されているかについて明示的に記憶しません。 むしろピクセルの色からそれを推測しようとします。 よって、そのピクセルが既に存在していたものか、 新たに設定されたものなのかは区別できません。 これは、画像で既に使われている色で画像を塗りつぶそうとすると、 望ましくない結果が得られることがあるということです。

# imagefilter

(PHP 5, PHP 7, PHP 8)

imagefilter — 画像にフィルタを適用する

### 説明

function 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` を返します。

### エラー / 例外

`IMG_FILTER_SCATTER` `filter` で `sub` または `plus` がオーバーフローやアンダーフローを引き起こす場合、 ValueError をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `IMG_FILTER_SCATTER` `filter` で `sub` または `plus` がオーバーフローやアンダーフローを引き起こす場合、 ValueError をスローするようになりました。
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.';
    }
    ?>

例2 imagefilter() 輝度の例

    <?php
    $im = imagecreatefrompng('sean.png');

    if($im && imagefilter($im, IMG_FILTER_BRIGHTNESS, 20))
    {
        echo 'Image brightness changed.';

        imagepng($im, 'sean.png');
    }
    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');
    }
    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);
    }
    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);

    // Output the differences
    header('Content-Type: image/png');
    imagepng($output);
    ?>

上の例の出力は、 たとえば以下のようになります。

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

上の例の出力は、 たとえば以下のようになります。

### 注意

> 注意: `IMG_FILTER_SCATTER` の適用結果は常にランダムです。

### 参考

- imageconvolution() - div および offset の係数を使用し、3x3 の畳み込み配列を適用する

# imageflip

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imageflip — 指定したモードで画像を反転させる

### 説明

function imageflip(GdImage `$image`, int `$mode`): true

`image` を、指定した `mode` で反転させます。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`mode`

  反転のモード。定数 `IMG_FLIP_*` のいずれかを指定します。

  定数 | 意味
  --- | ---
  `IMG_FLIP_HORIZONTAL` | 水平方向に、左右を反転させます。
  `IMG_FLIP_VERTICAL` | 垂直方向に、上下を反転させます。
  `IMG_FLIP_BOTH` | 水平方向、垂直方向の両方に反転させます。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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);
    ?>

上の例の出力は、 たとえば以下のようになります。

例2 水平方向の反転

この例では、定数 `IMG_FLIP_HORIZONTAL` を使います。

    <?php
    // 画像ファイル
    $filename = 'phplogo.png';

    // コンテントタイプ
    header('Content-type: image/png');

    // 読み込み
    $im = imagecreatefrompng($filename);

    // 水平反転
    imageflip($im, IMG_FLIP_HORIZONTAL);

    // 出力
    imagejpeg($im);
    ?>

上の例の出力は、 たとえば以下のようになります。

# imagefontheight

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefontheight — フォントの高さを取得する

### 説明

function 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() - 新しいフォントを読み込む

# imagefontwidth

(PHP 4, PHP 5, PHP 7, PHP 8)

imagefontwidth — フォントの幅を取得する

### 説明

function 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() - 新しいフォントを読み込む

# imageftbbox

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imageftbbox — freetype2 によるフォントを用いたテキストを囲む箱を取得する

### 説明

function 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);
    ?>

### 注意

> 注意: この関数は、PHP が FreeType サポート (--with-freetype-dir=DIR) を有効にしてコンパイルされている場合のみ使用可能です。

### 参考

- imagefttext() - FreeType 2 によるフォントを用いてイメージにテキストを描画する
- imagettfbbox() - TypeType フォントを使用したテキストの bounding box を生成する

# imagefttext

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagefttext — FreeType 2 によるフォントを用いてイメージにテキストを描画する

### 説明

function 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);
    ?>

### 注意

> 注意: この関数は、PHP が FreeType サポート (--with-freetype-dir=DIR) を有効にしてコンパイルされている場合のみ使用可能です。

### 参考

- imageftbbox() - freetype2 によるフォントを用いたテキストを囲む箱を取得する
- imagettftext() - TrueType フォントを使用してテキストを画像に書き込む

# imagegammacorrect

(PHP 4, PHP 5, PHP 7, PHP 8)

imagegammacorrect — GD イメージにガンマ補正を適用する

### 説明

function imagegammacorrect(GdImage `$image`, float `$input_gamma`, float `$output_gamma`): true

指定した GD 画像 `image` に 入力ガンマ値、出力ガンマ値を指定してガンマ補正を適用します。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`input_gamma`

  入力ガンマ値。

`output_gamma`

  出力ガンマ値。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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');
    ?>

# imagegd

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagegd — GD イメージをブラウザまたはファイルに出力する

### 説明

function imagegd(GdImage `$image`, ?string `$file` = `null`): bool

指定された `image` を GDフォーマットで出力するか、保存します。

### パラメータ

`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);
    ?>

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

### 注意

> 注意:

> 通常 GD フォーマットはイメージの一部を高速にロードするために 使用されます。GD フォーマットは GD 互換アプリケーションでのみ使用可能であることに注意してください。

警告

GD と GD2 画像フォーマットは libgd が作った独自仕様の画像フォーマットです。これらは obsolete と見なされているため、開発とテストの用途にだけ使うべきです。

### 参考

- imagegd2() - GD2 イメージをブラウザまたはファイルに出力する

# imagegd2

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imagegd2 — GD2 イメージをブラウザまたはファイルに出力する

### 説明

function imagegd2(
GdImage `$image`,
?string `$file` = `null`,
int `$chunk_size` = 128,
int `$mode` = `IMG_GD2_RAW`
): bool

指定された `image` を GD2フォーマットで出力するか、保存します。

### パラメータ

`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);
    ?>

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

### 注意

> 注意:

> 通常 GD2 フォーマットはイメージの一部を高速にロードするために 使用されます。GD2 フォーマットは GD2 互換アプリケーションでのみ使用可能であることに注意してください。

警告

GD と GD2 画像フォーマットは libgd が作った独自仕様の画像フォーマットです。これらは obsolete と見なされているため、開発とテストの用途にだけ使うべきです。

### 参考

- imagegd() - GD イメージをブラウザまたはファイルに出力する

# imagegetclip

(PHP 7 >= 7.2.0, PHP 8)

imagegetclip — 長方形を切り取り、画像として取得する

### 説明

function 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() - 切り取る長方形を設定する

# imagegetinterpolation

(PHP 8)

imagegetinterpolation — 補間方法を取得する

### 説明

function imagegetinterpolation(GdImage `$image`): int

`image` に現在設定されている補間方法を取得します。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。

### 戻り値

補間方法を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `image` は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な `gd` resource が期待されていました。

### 参考

- imagesetinterpolation() - 補間方法を設定する

# imagegif

(PHP 4, PHP 5, PHP 7, PHP 8)

imagegif — 画像をブラウザあるいはファイルに出力する

### 説明

function 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);
    ?>

例2 imagegif() による PNG 画像から GIF への変換

    <?php

    // PNG を読み込みます
    $png = imagecreatefrompng('./php.png');

    // 画像を GIF 形式で保存します
    imagegif($png, './php.gif');

    // 終了です
    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
>     {
>         die('No image support in this PHP server');
>     }
>     ?>

> 注意:

> 種々のイメージ関数のサポートを調べるために 関数 imagetypes() を使用することが可能です。

>     <?php
>     if(imagetypes() & IMG_GIF)
>     {
>         header('Content-type: image/gif');
>         imagegif($im);
>     }
>     elseif(imagetypes() & IMG_JPG)
>     {
>         /* ... etc. */
>     }
>     ?>

### 参考

- imagepng() - PNG イメージをブラウザまたはファイルに出力する
- imagewbmp() - 画像をブラウザあるいはファイルに出力する
- imagejpeg() - 画像をブラウザあるいはファイルに出力する
- imagetypes() - この PHP がサポートしている画像形式を返す

# imagegrabscreen

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

imagegrabscreen — 画面全体をキャプチャする

### 説明

function imagegrabscreen(): GdImage|false

画面全体のスクリーンショットを取得します。

> 注意:

> この関数は Windows 上でのみ使用できます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に画像オブジェクト、失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | 成功時には、 この関数は GDImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。

### 例

例1 imagegrabscreen() の例

この例は、現在の画面の状態のスクリーンショットを取得してそれを png 画像として保存するものです。

    <?php
    $im = imagegrabscreen();
    imagepng($im, "myscreenshot.png");
    ?>

### 参考

- imagegrabwindow() - ウィンドウをキャプチャする

# imagegrabwindow

(PHP 5 >= 5.2.2, PHP 7, PHP 8)

imagegrabwindow — ウィンドウをキャプチャする

### 説明

function 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");
    ?>

ウィンドウ (ここでは 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");
    ?>

### 参考

- imagegrabscreen() - 画面全体をキャプチャする

# imageinterlace

(PHP 4, PHP 5, PHP 7, PHP 8)

imageinterlace — インターレースを有効もしくは無効にする

### 説明

function imageinterlace(GdImage `$image`, ?bool `$enable` = `null`): bool

imageinterlace() は、インターレースビットをon またはoffに切り替えます。

インターレースビットがonでかつその画像が JPEG の場合、 その画像はプログレッシブ JPEG として生成されています。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`enable`

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

# imageistruecolor

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imageistruecolor — 画像が truecolor かどうか調べる

### 説明

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

        $im = $tc;
        $tc = NULL;

        // あるいは imagepalettetotruecolor() を使います
    }

    // 画像のインスタンスに対する操作を続けます
    ?>

### 参考

- imagecreatetruecolor() - TrueColor イメージを新規に作成する
- imagepalettetotruecolor() - パレット形式の画像を true color に変換する

# imagejpeg

(PHP 4, PHP 5, PHP 7, PHP 8)

imagejpeg — 画像をブラウザあるいはファイルに出力する

### 説明

function 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` を返します。

### エラー / 例外

`quality` が不正の場合、 ValueError をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `image` は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な `gd` resource が期待されていました。
8.4.0 | `quality` が不正の場合、 ValueError をスローするようになりました。

### 例

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

上の例の出力は、 たとえば以下のようになります。

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

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

### 注意

> 注意:

> プログレッシブ JPEG を出力したい場合には、 imageinterlace() でインターレースをセットする必要があります。

### 参考

- imagepng() - PNG イメージをブラウザまたはファイルに出力する
- imagegif() - 画像をブラウザあるいはファイルに出力する
- imagewbmp() - 画像をブラウザあるいはファイルに出力する
- imageinterlace() - インターレースを有効もしくは無効にする
- imagetypes() - この PHP がサポートしている画像形式を返す

# imagelayereffect

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagelayereffect — アルファブレンディングフラグを設定し、レイヤ効果を使用する

### 説明

function imagelayereffect(GdImage `$image`, int `$effect`): true

アルファブレンディングフラグを設定し、レイヤ効果を使用します。

### パラメータ

`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` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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);
    ?>

上の例の出力は、 たとえば以下のようになります。

# imageline

(PHP 4, PHP 5, PHP 7, PHP 8)

imageline — 直線を描画する

### 説明

function imageline(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

指定したふたつの点を結ぶ直線を描画します。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`x1`

  最初の点の x 座標。

`y1`

  最初の点の y 座標。

`x2`

  二番目の点の x 座標。

`y2`

  二番目の点の y 座標。

`color`

  直線の色。imagecolorallocate() で作成された色識別子。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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() - 画像で使用する色を作成する

# imageloadfont

(PHP 4, PHP 5, PHP 7, PHP 8)

imageloadfont — 新しいフォントを読み込む

### 説明

function 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);
    ?>

### 参考

- imagefontwidth() - フォントの幅を取得する
- imagefontheight() - フォントの高さを取得する
- imagestring() - 文字列を水平に描画する

# imageopenpolygon

(PHP 7 >= 7.2.0, PHP 8)

imageopenpolygon — オープンポリゴンを描画する

### 説明

PHP 8.0.0 以降のシグネチャ (名前付き引数をサポートしていません)

function imageopenpolygon(GdImage `$image`, array `$points`, int `$color`): bool

代替のシグネチャ (PHP 8.1.0 以降は非推奨)

function 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);
    ?>

上の例の出力は、 たとえば以下のようになります。

### 参考

- imagepolygon() - 多角形を描画する

# imagepalettecopy

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagepalettecopy — あるイメージから他のイメージにパレットをコピーする

### 説明

function 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);
    ?>

# imagepalettetotruecolor

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagepalettetotruecolor — パレット形式の画像を true color に変換する

### 説明

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

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

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

    typeof($im) = palette
    typeof($im) = true color

### 参考

- imagecreatetruecolor() - TrueColor イメージを新規に作成する
- imageistruecolor() - 画像が truecolor かどうか調べる

# imagepng

(PHP 4, PHP 5, PHP 7, PHP 8)

imagepng — PNG イメージをブラウザまたはファイルに出力する

### 説明

function 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_*` の組み合わせを指定します。 `PNG_NO_FILTER` や `PNG_ALL_FILTERS` を使用すると、 全フィルタを一括で無効にしたり有効にしたりできます。 デフォルト値 (`-1`) は、フィルタリングを無効にします。

  警告

  システムにインストールされた libgd は、`filters` パラメータを無視します。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は `true` を返します。

### エラー / 例外

`quality` が不正の場合、 ValueError をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `quality` が不正の場合、 ValueError をスローするようになりました。
8.0.0 | `image` は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な `gd` resource が期待されていました。

### 例

    <?php
    $im = imagecreatefrompng("test.png");

    header('Content-Type: image/png');

    imagepng($im);
    ?>

### 参考

- imagegif() - 画像をブラウザあるいはファイルに出力する
- imagewbmp() - 画像をブラウザあるいはファイルに出力する
- imagejpeg() - 画像をブラウザあるいはファイルに出力する
- imagetypes() - この PHP がサポートしている画像形式を返す
- imagesavealpha() - 画像を保存する際に、完全なアルファチャネル情報を保存するかどうかを指定する

# imagepolygon

(PHP 4, PHP 5, PHP 7, PHP 8)

imagepolygon — 多角形を描画する

### 説明

PHP 8.0.0 以降のシグネチャ(名前付き引数をサポートしていません)

function imagepolygon(GdImage `$image`, array `$points`, int `$color`): bool

代替のシグネチャ (PHP 8.1.0 以降は非推奨)

function 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);
    ?>

上の例の出力は、 たとえば以下のようになります。

### 参考

- imagefilledpolygon() - 塗りつぶした多角形を描画する
- imageopenpolygon() - オープンポリゴンを描画する
- imagecreate() - パレットを使用する新規画像を作成する
- imagecreatetruecolor() - TrueColor イメージを新規に作成する

# imagerectangle

(PHP 4, PHP 5, PHP 7, PHP 8)

imagerectangle — 矩形を描画する

### 説明

function imagerectangle(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`,
int `$color`
): true

imagerectangle() は、指定した座標から始まる矩形を作成します。 0, 0 が画像の左上隅を表します。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`x1`

  左上の x 座標。

`y1`

  左上の y 座標。

`x2`

  右下の x 座標。

`y2`

  右下の y 座標。

`color`

  imagecolorallocate() で作成された色識別子。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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);
    ?>

上の例の出力は、 たとえば以下のようになります。

# imageresolution

(PHP 7 >= 7.2.0, PHP 8)

imageresolution — 画像の解像度を取得/設定する

### 説明

function imageresolution(GdImage `$image`, ?int `$resolution_x` = `null`, ?int `$resolution_y` = `null`): array|true

imageresolution() 関数は、 画像の解像度を DPI(dots per inch) 単位で取得/設定します。 オプションのパラメータが `null` だった場合は、 現在の解像度を配列で返します。 `resolution_x` だけが `null` でない場合、 垂直/水平方向の解像度がこの値に設定されます。 オプションのパラメータが両方指定されると、 垂直/水平方向の解像度がそれぞれ指定された値に設定されます。

この手の情報をサポートしている画像フォーマットを読み書きする場合(現状、PNG と JPEG)に、 解像度情報はメタ情報としてのみ使われます。画像を描画する操作には一切影響しません。 新しい画像の解像度は 96DPI です。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`resolution_x`

  水平方向の解像度をDPI単位で指定します。

`resolution_y`

  垂直方向の解像度をDPI単位で指定します。

### 戻り値

getter として使う場合、 水平方向と垂直方向の解像度を成功時に返します。 setter として使う場合、常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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
    )

# imagerotate

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imagerotate — 指定された角度で画像を回転する

### 説明

function 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);
    ?>

上の例の出力は、 たとえば以下のようになります。

### 注意

> 注意: この関数は、imagesetinterpolation() で設定した補間方式の影響を受けます。

### 参考

- imagesetinterpolation() - 補間方法を設定する

# imagesavealpha

(PHP 4 >= 4.3.2, PHP 5, PHP 7, PHP 8)

imagesavealpha — 画像を保存する際に、完全なアルファチャネル情報を保存するかどうかを指定する

### 説明

function imagesavealpha(GdImage `$image`, bool `$enable`): true

imagesavealpha() は 画像を保存する際に（単一色の透過設定ではない）完全な アルファチャネル情報を保存するフラグを設定します。 この関数は、完全なアルファチャンネル情報をサポートしている画像フォーマット、 つまり、`PNG`, `WebP`, `AVIF` をサポートしています。

> 注意: imagesavealpha() は、`PNG` でのみ意味があります。 なぜなら、完全なアルファチャンネル情報を `WebP`, `AVIF` は常に保存するからです。 この振る舞いは将来変更される可能性があるので、依存すべきではありません。 よって、`WebP` や `AVIF` 画像であっても imagesavealpha() を意図的にコールすべきです。

アルファチャネルを保存するためには、まずアルファブレンディングを解除する必要があります (`imagealphablending($im, false)`)。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`enable`

  アルファチャネルを保存するか否か。デフォルトは `false` です。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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);
    ?>

### 参考

- imagealphablending() - イメージのブレンドモードを設定する

# imagescale

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagescale — 幅と高さを指定して、画像の縮尺を変更する

### 説明

function 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` を返します。

### エラー / 例外

`width` または `height` がオーバーフローやアンダーフローを引き起こす場合、 ValueError をスローします。

`mode` が不正の場合、 ValueError をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `width` または `height` がオーバーフローやアンダーフローを引き起こす場合でも、 ValueError をスローするようになりました。
8.4.0 | `mode` が不正の場合、 ValueError をスローするようになりました。
8.0.0 | 成功時には、 この関数は GDImage クラスのインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。
8.0.0 | `image` は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な `gd` resource が期待されていました。

### 参考

- imagecopyresized() - 画像の一部をコピーしサイズを変更する
- imagecopyresampled() - 再サンプリングを行いイメージの一部をコピー、伸縮する

# imagesetbrush

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetbrush — 線の描画用にブラシイメージを設定する

### 説明

function imagesetbrush(GdImage `$image`, GdImage `$brush`): true

imagesetbrush() は、特別な色 `IMG_COLOR_BRUSHED` または `IMG_COLOR_STYLEDBRUSHED` で描画される際に (imageline() や imagepolygon() のような) 全ての線描画関数で使用されるブラシイメージを設定します。

警告

ブラシの使用が終った際には特別な処理は不要ですが、 ブラシイメージを破棄する(もしくは、PHPに破棄させる)場合には、新たにブラシイメージを設定するまでは、 色 `IMG_COLOR_BRUSHED` または `IMG_COLOR_STYLEDBRUSHED` を使用するべきではありません。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`brush`

  画像オブジェクト。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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, 99, 99, $white);

    // ブラシを設定します
    imagesetbrush($im, $php);

    // いくつかのブラシを重ねます
    imageline($im, 50, 50, 50, 60, IMG_COLOR_BRUSHED);

    // 画像をブラウザに出力します
    header('Content-type: image/png');

    imagepng($im);
    ?>

上の例の出力は、 たとえば以下のようになります。

# imagesetclip

(PHP 7 >= 7.2.0, PHP 8)

imagesetclip — 切り取る長方形を設定する

### 説明

function imagesetclip(
GdImage `$image`,
int `$x1`,
int `$y1`,
int `$x2`,
int `$y2`
): true

imagesetclip() は、切り取る長方形を設定します。 つまり、ピクセルが存在しない状態でなければ描画されます。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`x1`

  左上のx座標

`y1`

  左上のy座標

`x2`

  右下のx座標

`y2`

  右下のy座標

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `image` は、 GdImage クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な `gd` resource が期待されていました。

### 参考

- imagegetclip() - 長方形を切り取り、画像として取得する

# imagesetinterpolation

(PHP 5 >= 5.5.0, PHP 7, PHP 8)

imagesetinterpolation — 補間方法を設定する

### 説明

function 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() - 補間方法を取得する

# imagesetpixel

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesetpixel — 点を生成する

### 説明

function imagesetpixel(
GdImage `$image`,
int `$x`,
int `$y`,
int `$color`
): true

imagesetpixel() は、指定した座標にピクセルを描画します。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`x`

  x 座標。

`y`

  y 座標。

`color`

  imagecolorallocate() で作成された色識別子。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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);

    ?>

上の例の出力は、 たとえば以下のようになります。

### 参考

- imagecreatetruecolor() - TrueColor イメージを新規に作成する
- imagecolorallocate() - 画像で使用する色を作成する
- imagecolorat() - ピクセルの色のインデックスを取得する

# imagesetstyle

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetstyle — 線描画用のスタイルを設定する

### 説明

function 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);
    ?>

上の例の出力は、 たとえば以下のようになります。

### 参考

- imagesetbrush() - 線の描画用にブラシイメージを設定する
- imageline() - 直線を描画する

# imagesetthickness

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesetthickness — 線描画用の線幅を設定する

### 説明

function imagesetthickness(GdImage `$image`, int `$thickness`): true

imagesetthickness() は、長方形、多角形、弧などを描画する際の線幅を `thickness` ピクセルに設定します。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`thickness`

  ピクセル単位の線幅。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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, 199, 99, $white);

    // 線幅を 5 に設定します
    imagesetthickness($im, 5);

    // 矩形を描画します
    imagerectangle($im, 14, 14, 185, 85, $black);

    // 画像をブラウザに出力します
    header('Content-Type: image/png');

    imagepng($im);
    ?>

上の例の出力は、 たとえば以下のようになります。

# imagesettile

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagesettile — 塗りつぶし用のイメージを設定する

### 説明

function imagesettile(GdImage `$image`, GdImage `$tile`): true

imagesettile() は、特別な色 `IMG_COLOR_TILED` を指定して塗りつぶされた場合に、 (imagefill() や imagefilledpolygon() のような) 領域塗りつぶし関数で使用されるタイルイメージを設定します。

タイルは、領域を塗りつぶすために繰り返し使用されるイメージです。 全ての GD イメージをタイルとして使用可能で、 imagecolortransparent() でタイルの透過色 ID を設定することにより、 その一部から下の部分が透けて見えるようなタイルを作成することが可能です。

警告

タイルの使用が終った際には、特別な処理は不要ですが、 タイルイメージを破棄する(もしくは、PHPに破棄させる)場合には、 新たにタイルイメージを設定するまでは、色 `IMG_COLOR_TILED` を使用してはいけません。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`tile`

  タイルとして使用する画像オブジェクト。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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);
    ?>

上の例の出力は、 たとえば以下のようになります。

# imagestring

(PHP 4, PHP 5, PHP 7, PHP 8)

imagestring — 文字列を水平に描画する

### 説明

function imagestring(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$string`,
int `$color`
): true

指定した座標に文字列 `string` を描画します。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`font`
  latin2 エンコーディングの組み込みのフォントの場合は 1, 2, 3, 4, 5 のいずれか (数字が大きなほうが、より大きいフォントに対応します)、あるいは imageloadfont() が返した、GdFont クラスのインスタンスのいずれか。
`x`

  左上隅の x 座標。

`y`

  左上隅の y 座標。

`string`

  書き出す文字列。

`color`

  imagecolorallocate() で作成された色識別子。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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);
    ?>

上の例の出力は、 たとえば以下のようになります。

### 参考

- imagestringup() - 文字列を垂直に描画する
- imageloadfont() - 新しいフォントを読み込む
- imagettftext() - TrueType フォントを使用してテキストを画像に書き込む

# imagestringup

(PHP 4, PHP 5, PHP 7, PHP 8)

imagestringup — 文字列を垂直に描画する

### 説明

function imagestringup(
GdImage `$image`,
GdFont|int `$font`,
int `$x`,
int `$y`,
string `$string`,
int `$color`
): true

文字列 `string` を、指定した座標で垂直に描画します。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`font`
  latin2 エンコーディングの組み込みのフォントの場合は 1, 2, 3, 4, 5 のいずれか (数字が大きなほうが、より大きいフォントに対応します)、あるいは imageloadfont() が返した、GdFont クラスのインスタンスのいずれか。
`x`

  左下隅の x 座標。

`y`

  左下隅の y 座標。

`string`

  書き出す文字列。

`color`

  imagecolorallocate() で作成された色識別子。

### 戻り値

常に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
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');
    ?>

上の例の出力は、 たとえば以下のようになります。

### 参考

- imagestring() - 文字列を水平に描画する
- imageloadfont() - 新しいフォントを読み込む

# imagesx

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesx — 画像の幅を取得する

### 説明

function 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() - 画像の高さを取得する

# imagesy

(PHP 4, PHP 5, PHP 7, PHP 8)

imagesy — 画像の高さを取得する

### 説明

function 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() - 画像の幅を取得する

# imagetruecolortopalette

(PHP 4 >= 4.0.6, PHP 5, PHP 7, PHP 8)

imagetruecolortopalette — TrueColor イメージをパレットイメージに変換する

### 説明

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

# imagettfbbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imagettfbbox — TypeType フォントを使用したテキストの bounding box を生成する

### 説明

function 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`

  測定する文字列。

`options`

  imagettftext() と同じです。

### 戻り値

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

### 注意

> 注意: この関数は、PHP が FreeType サポート (--with-freetype-dir=DIR) を有効にしてコンパイルされている場合のみ使用可能です。

### 参考

- imagettftext() - TrueType フォントを使用してテキストを画像に書き込む
- imageftbbox() - freetype2 によるフォントを用いたテキストを囲む箱を取得する

# imagettftext

(PHP 4, PHP 5, PHP 7, PHP 8)

imagettftext — TrueType フォントを使用してテキストを画像に書き込む

### 説明

function 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 文字列にすることを検討してください。

  フォントでサポートされていない文字が文字列で使用されている場合、 その文字は白抜きの矩形に置き換えられます。

`options`

  `linespacing` キーに float 値を指定した配列。

### 戻り値

テキストの境界を 構成する 4 点を表す 8 個の要素を有する配列を返します。 返される点は左下、右下、右上、左上の順番となります。 点の座標は、角度によらず text に関する相対座標として表されます。 つまり、"左上"は、text を水平に見た場合の左上の隅を表します。 エラー時には `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `options` が追加されました。

### 例

例1 imagettftext() の例

この例は、400x30 ピクセルの白地に Arial フォントを用いて、黒字 (グレーの影付き) で "Testing..." と書かれた PNG を作成します。

    <?php

    // content-type を設定します
    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);

    ?>

上の例の出力は、 たとえば以下のようになります。

### 注意

> 注意: この関数は、PHP が FreeType サポート (--with-freetype-dir=DIR) を有効にしてコンパイルされている場合のみ使用可能です。

### 参考

- imagettfbbox() - TypeType フォントを使用したテキストの bounding box を生成する
- imagefttext() - FreeType 2 によるフォントを用いてイメージにテキストを描画する
- imagestring() - 文字列を水平に描画する

# imagetypes

(PHP 4 >= 4.0.2, PHP 5, PHP 7, PHP 8)

imagetypes — この PHP がサポートしている画像形式を返す

### 説明

function 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ライブラリに関する情報を取得する

# imagewbmp

(PHP 4 >= 4.0.1, PHP 5, PHP 7, PHP 8)

imagewbmp — 画像をブラウザあるいはファイルに出力する

### 説明

function 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);
    ?>

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

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

### 参考

- image2wbmp() - 画像をブラウザあるいはファイルに出力する
- imagepng() - PNG イメージをブラウザまたはファイルに出力する
- imagegif() - 画像をブラウザあるいはファイルに出力する
- imagejpeg() - 画像をブラウザあるいはファイルに出力する
- imagetypes() - この PHP がサポートしている画像形式を返す

# imagewebp

(PHP 5 >= 5.4.0, PHP 7, PHP 8)

imagewebp — WebP 画像をブラウザあるいはファイルに出力する

### 説明

function imagewebp(GdImage `$image`, resource|string|null `$file` = `null`, int `$quality` = -1): bool

指定した `image` を、WebP 形式で出力あるいは保存します。

### パラメータ

`image`
  imagecreatetruecolor()のような画像作成関数が返す GdImage オブジェクト。
`file`

  ファイル保存先のパスあるいはオープン中のリソース (この関数が値を戻した後で自動的にクローズされます)。省略したり `null` を設定したりした場合は、画像ストリームを直接出力します。

`quality`

  `quality` には、0 (品質は最低で、 ファイルサイズが小さくなる) から 100 (品質が最高で、ファイルサイズは大きくなる) までの値を指定します。 `-1` を指定すると、 デフォルト値 `80` を使います。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

警告

しかしながら、libgd がイメージの出力に失敗した場合、この関数は `true` を返します。

### エラー / 例外

`quality` が不正の場合、 ValueError をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `quality` が不正の場合、 ValueError をスローするようになりました。
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');
    ?>

# imagexbm

(PHP 5, PHP 7, PHP 8)

imagexbm — XBM 画像をブラウザあるいはファイルに出力する

### 説明

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

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

# iptcembed

(PHP 4, PHP 5, PHP 7, PHP 8)

iptcembed — バイナリ IPTC データを JPEG イメージに埋めこむ

### 説明

function 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 画像ライブラリは必要ありません。

# iptcparse

(PHP 4, PHP 5, PHP 7, PHP 8)

iptcparse — バイナリの IPTC ブロックのタグをパースする

### 説明

function 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 画像ライブラリは必要ありません。

# jpeg2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

jpeg2wbmp — JPEG画像をWBMP画像に変換する

警告

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

### 説明

function 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画像に変換する

# png2wbmp

(PHP 4 >= 4.0.5, PHP 5, PHP 7)

png2wbmp — PNG画像をWBMP画像に変換する

警告

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

### 説明

function 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画像に変換する

## 目次

- 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 クラス

(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 {
}

- インストール/設定
  - 要件
  - インストール手順
  - 実行時設定
  - リソース型
- 定義済み定数
- 例
  - 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 クラス

# Gmagick

# はじめに

警告

この拡張モジュールは、 実験的 なものです。この拡張モジュールの動作・ 関数名・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 このモジュールは自己責任で使用してください。

Gmagick は、GraphicsMagick API を用いて画像の作成や編集を行ったり画像のメタ情報を取得したりするための拡張モジュールです。

GraphicsMagick は、自らを「画像処理におけるスイスアーミーナイフ」と称しています。 88 の主要なフォーマットに対応しており、よく使われる DPX、GIF、JPEG、JPEG-2000、 PNG、PDF、PNM そして TIFF もそれに含まれます。

Gmagick は、メインとなる Gmagick クラスのほかに描画のエフェクトを担当する GmagickDraw クラスと画像の各ピクセル (色、透明度) をあらわす GmagickPixel クラスで構成されています。

# インストール/設定

## 目次

- 要件
- インストール手順

## 要件

この拡張モジュールは、GraphicsMagick バージョン 1.4 以降 で最もうまく動作します。 Gmagick は GraphicsMagick 1.2.6 までの旧バージョンでも動作しますが、 旧バージョンでは対応していない機能やフォーマットがあります。 Windows 版の GraphicsMagick は、GraphicsMagick のウェブサイトから取得できます。 ImageMagick と GraphicsMagick の違いについては、 » FAQ を参照ください。

## インストール手順

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/gmagick.

> 注意: この拡張モジュールの正式な名前は 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 function __construct(string `$filename` = ?)
public function addimage(Gmagick `$source`): Gmagick
public function addnoiseimage(int `$noise_type`): Gmagick
public function annotateimage(
GmagickDraw `$GmagickDraw`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): Gmagick
public function blurimage(float `$radius`, float `$sigma`, int `$channel` = ?): Gmagick
public function borderimage(GmagickPixel `$color`, int `$width`, int `$height`): Gmagick
public function charcoalimage(float `$radius`, float `$sigma`): Gmagick
public function chopimage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): Gmagick
public function clear(): Gmagick
public function commentimage(string `$comment`): Gmagick
public function compositeimage(
Gmagick `$source`,
int `$COMPOSE`,
int `$x`,
int `$y`
): Gmagick
public function cropimage(
int `$width` ,
int `$height` ,
int `$x`,
int `$y`
): Gmagick
public function cropthumbnailimage(int `$width`, int `$height`): Gmagick
public function current(): Gmagick
public function cyclecolormapimage(int `$displace`): Gmagick
public function deconstructimages(): Gmagick
public function despeckleimage(): Gmagick
public function destroy(): bool
public function drawimage(GmagickDraw `$GmagickDraw`): Gmagick
public function edgeimage(float `$radius`): Gmagick
public function embossimage(float `$radius`, float `$sigma`): Gmagick
public function enhanceimage(): Gmagick
public function equalizeimage(): Gmagick
public function flipimage(): Gmagick
public function flopimage(): Gmagick
public function frameimage(
GmagickPixel `$color`,
int `$width`,
int `$height`,
int `$inner_bevel`,
int `$outer_bevel`
): Gmagick
public function gammaimage(float `$gamma`): Gmagick
public function getcopyright(): string
public function getfilename(): string
public function getimagebackgroundcolor(): GmagickPixel
public function getimageblueprimary(): array
public function getimagebordercolor(): GmagickPixel
public function getimagechanneldepth(int `$channel_type`): int
public function getimagecolors(): int
public function getimagecolorspace(): int
public function getimagecompose(): int
public function getimagedelay(): int
public function getimagedepth(): int
public function getimagedispose(): int
public function getimageextrema(): array
public function getimagefilename(): string
public function getimageformat(): string
public function getimagegamma(): float
public function getimagegreenprimary(): array
public function getimageheight(): int
public function getimagehistogram(): array
public function getimageindex(): int
public function getimageinterlacescheme(): int
public function getimageiterations(): int
public function getimagematte(): int
public function getimagemattecolor(): GmagickPixel
public function getimageprofile(string `$name`): string
public function getimageredprimary(): array
public function getimagerenderingintent(): int
public function getimageresolution(): array
public function getimagescene(): int
public function getimagesignature(): string
public function getimagetype(): int
public function getimageunits(): int
public function getimagewhitepoint(): array
public function getimagewidth(): int
public function getpackagename(): string
public function getquantumdepth(): array
public function getreleasedate(): string
public function getsamplingfactors(): array
public function getsize(): array
public function getversion(): array
public function hasnextimage(): mixed
public function haspreviousimage(): mixed
public function implodeimage(float `$radius`): mixed
public function labelimage(string `$label`): mixed
public function levelimage(
float `$blackPoint`,
float `$gamma`,
float `$whitePoint`,
int `$channel` = Gmagick::CHANNEL_DEFAULT
): mixed
public function magnifyimage(): mixed
public function mapimage(gmagick `$gmagick`, bool `$dither`): Gmagick
public function medianfilterimage(float `$radius`): void
public function minifyimage(): Gmagick
public function modulateimage(float `$brightness`, float `$saturation`, float `$hue`): Gmagick
public function motionblurimage(float `$radius`, float `$sigma`, float `$angle`): Gmagick
public function newimage(
int `$width`,
int `$height`,
string `$background`,
string `$format` = ?
): Gmagick
public function nextimage(): bool
public function normalizeimage(int `$channel` = ?): Gmagick
public function oilpaintimage( float `$radius` ): Gmagick
public function previousimage(): bool
public function profileimage(string `$name`, string `$profile`): Gmagick
public function quantizeimage(
int `$numColors`,
int `$colorspace`,
int `$treeDepth`,
bool `$dither`,
bool `$measureError`
): Gmagick
public function quantizeimages(
int `$numColors`,
int `$colorspace`,
int `$treeDepth`,
bool `$dither`,
bool `$measureError`
): Gmagick
public function queryfontmetrics(GmagickDraw `$draw`, string `$text`): array
public function queryfonts(string `$pattern` = "*"): array
public function queryformats(string `$pattern` = "*"): array
public function radialblurimage(float `$angle`, int `$channel` = Gmagick::CHANNEL_DEFAULT): Gmagick
public function raiseimage(
int `$width`,
int `$height`,
int `$x`,
int `$y`,
bool `$raise`
): Gmagick
public function read(string `$filename`): Gmagick
public function readimage(string `$filename`): Gmagick
public function readimageblob(string `$imageContents`, string `$filename` = ?): Gmagick
public function readimagefile(resource `$fp`, string `$filename` = ?): Gmagick
public function reducenoiseimage(float `$radius`): Gmagick
public function removeimage(): Gmagick
public function removeimageprofile(string `$name`): string
public function resampleimage(
float `$xResolution`,
float `$yResolution`,
int `$filter`,
float `$blur`
): Gmagick
public function resizeimage(
int `$width`,
int `$height`,
int `$filter`,
float `$blur`,
bool `$fit` = `false`
): Gmagick
public function rollimage(int `$x`, int `$y`): Gmagick
public function rotateimage(mixed `$color`, float `$degrees`): Gmagick
public function scaleimage(int `$width`, int `$height`, bool `$fit` = `false`): Gmagick
public function separateimagechannel(int `$channel`): Gmagick
function setCompressionQuality( int `$quality` ): Gmagick
public function setfilename(string `$filename`): Gmagick
public function setimagebackgroundcolor(GmagickPixel `$color`): Gmagick
public function setimageblueprimary(float `$x`, float `$y`): Gmagick
public function setimagebordercolor(GmagickPixel `$color`): Gmagick
public function setimagechanneldepth(int `$channel`, int `$depth`): Gmagick
public function setimagecolorspace(int `$colorspace`): Gmagick
public function setimagecompose(int `$composite`): Gmagick
public function setimagedelay(int `$delay`): Gmagick
public function setimagedepth(int `$depth`): Gmagick
public function setimagedispose(int `$disposeType`): Gmagick
public function setimagefilename(string `$filename`): Gmagick
public function setimageformat(string `$imageFormat`): Gmagick
public function setimagegamma(float `$gamma`): Gmagick
public function setimagegreenprimary(float `$x`, float `$y`): Gmagick
public function setimageindex(int `$index`): Gmagick
public function setimageinterlacescheme(int `$interlace`): Gmagick
public function setimageiterations(int `$iterations`): Gmagick
public function setimageprofile(string `$name`, string `$profile`): Gmagick
public function setimageredprimary(float `$x`, float `$y`): Gmagick
public function setimagerenderingintent(int `$rendering_intent`): Gmagick
public function setimageresolution(float `$xResolution`, float `$yResolution`): Gmagick
public function setimagescene(int `$scene`): Gmagick
public function setimagetype(int `$imgType`): Gmagick
public function setimageunits(int `$resolution`): Gmagick
public function setimagewhitepoint(float `$x`, float `$y`): Gmagick
public function setsamplingfactors(array `$factors`): Gmagick
public function setsize(int `$columns`, int `$rows`): Gmagick
public function shearimage(mixed `$color`, float `$xShear`, float `$yShear`): Gmagick
public function solarizeimage(int `$threshold`): Gmagick
public function spreadimage(float `$radius`): Gmagick
public function stripimage(): Gmagick
public function swirlimage(float `$degrees`): Gmagick
public function thumbnailimage(int `$width`, int `$height`, bool `$fit` = `false`): Gmagick
public function trimimage(float `$fuzz`): Gmagick
public function writeimage(string `$filename`, bool `$all_frames` = `false`): Gmagick
}

# Gmagick::addimage

(PECL gmagick >= Unknown)

Gmagick::addimage — 新しい画像を Gmagick オブジェクトの画像リストに追加する

### 説明

public function Gmagick::addimage(Gmagick `$source`): Gmagick

新しい画像を、ソースオブジェクトの現在位置から Gmagick オブジェクトに追加します。 この操作の後は、イテレータの位置がリストの末尾に移動します。

### パラメータ

`source`
  ソース Gmagick オブジェクト。

### 戻り値

Gmagick オブジェクトに画像を追加して返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::addnoiseimage

(PECL gmagick >= Unknown)

Gmagick::addnoiseimage — ランダムなノイズを画像に追加する

### 説明

public function Gmagick::addnoiseimage(int `$noise_type`): Gmagick

ランダムなノイズを画像に追加します。

### パラメータ

`noise_type`
  ノイズの形式。 ノイズ定数 の一覧を参照ください。

### 戻り値

Gmagick オブジェクトにノイズを追加して返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::annotateimage

(PECL gmagick >= Unknown)

Gmagick::annotateimage — 画像にテキストによる注記を加える

### 説明

public function Gmagick::annotateimage(
GmagickDraw `$GmagickDraw`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): Gmagick

テキストによる注記を画像に加えます。

### パラメータ

`GmagickDraw`
  テキスト描画設定を含む GmagickDraw オブジェクト。
`x`
  テキストの左端の水平オフセットをあらわすピクセル数。
`y`
  テキストのベースラインの垂直オフセットをあらわすピクセル数。
`angle`
  テキストを書き出す角度。
`text`
  描画するテキスト。

### 戻り値

Gmagick オブジェクトに注記を加えて返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::blurimage

(PECL gmagick >= Unknown)

Gmagick::blurimage — blur (にじみ) フィルタを画像に追加する

### 説明

public function Gmagick::blurimage(float `$radius`, float `$sigma`, int `$channel` = ?): Gmagick

blur (にじみ) フィルタを画像に追加します。

### パラメータ

`radius`
  にじみの半径。
`sigma`
  標準偏差。

### 戻り値

にじませた Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::borderimage

(PECL gmagick >= Unknown)

Gmagick::borderimage — 画像の周りを枠線で囲む

### 説明

public function Gmagick::borderimage(GmagickPixel `$color`, int `$width`, int `$height`): Gmagick

画像の周りを枠線で囲みます。枠線の色は GmagickPixel オブジェクトあるいは色文字列で指定します。

### パラメータ

`color`
  枠線の色を含む GmagickPixel オブジェクトあるいは文字列。
`width`
  枠線の幅。
`height`
  枠線の高さ。

### 戻り値

枠線を定義した Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::charcoalimage

(PECL gmagick >= Unknown)

Gmagick::charcoalimage — 木炭画をシミュレートする

### 説明

public function Gmagick::charcoalimage(float `$radius`, float `$sigma`): Gmagick

木炭画をシミュレートします。

### パラメータ

`radius`
  ガウス分布の半径。中心を含まないピクセル数。
`sigma`
  ガウス分布の標準偏差 (ピクセル単位)。

### 戻り値

木炭画をシミュレートした Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::chopimage

(PECL gmagick >= Unknown)

Gmagick::chopimage — 画像の一部を取り除き、切り詰める

### 説明

public function Gmagick::chopimage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): Gmagick

画像の一部を削除し、そこにあった画像をなくします。

### パラメータ

`width`
  切り取る範囲の幅。
`height`
  切り取る範囲の高さ。
`x`
  切り取る範囲の X 座標。
`y`
  切り取る範囲の Y 座標。

### 戻り値

切り取った後の Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::clear

(PECL gmagick >= Unknown)

Gmagick::clear — Gmagick オブジェクトに関連付けられたすべてのリソースをクリアする

### 説明

public function Gmagick::clear(): Gmagick

Gmagick オブジェクトに関連付けられたすべてのリソースをクリアします。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

クリアした Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::commentimage

(PECL gmagick >= Unknown)

Gmagick::commentimage — コメントを画像に追加する

### 説明

public function Gmagick::commentimage(string `$comment`): Gmagick

コメントを画像に追加します。

### パラメータ

`comment`
  追加するコメント。

### 戻り値

コメントを追加した Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::compositeimage

(PECL gmagick >= Unknown)

Gmagick::compositeimage — ある画像を別の画像に合成する

### 説明

public function Gmagick::compositeimage(
Gmagick `$source`,
int `$COMPOSE`,
int `$x`,
int `$y`
): Gmagick

ある画像を、別の画像の指定した位置に合成します。

### パラメータ

`source`
  合成する画像を保持する Gmagick オブジェクト。
`COMPOSE`
  合成演算子。
`x`
  合成する位置の列オフセット。
`y`
  合成する位置の行オフセット。

### 戻り値

合成した Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::__construct

(PECL gmagick >= Unknown)

Gmagick::__construct — Gmagick のコンストラクタ

### 説明

public function Gmagick::__construct(string `$filename` = ?)

Gmagick のコンストラクタです。

### パラメータ

`filename`
  読み込みたい画像へのパス、あるいは複数のパスの配列。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::cropimage

(PECL gmagick >= Unknown)

Gmagick::cropimage — 画像の一部を抽出する

### 説明

public function Gmagick::cropimage(
int `$width` ,
int `$height` ,
int `$x`,
int `$y`
): Gmagick

画像の一部を抽出します。

### パラメータ

`width`
  抽出する幅。
`height`
  抽出する高さ。
`x`
  抽出する領域の左上の X 座標。
`y`
  抽出する領域の左上の Y 座標。

### 戻り値

抽出した Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::cropthumbnailimage

(PECL gmagick >= Unknown)

Gmagick::cropthumbnailimage — 切り取ってサムネイルを作成する

### 説明

public function Gmagick::cropthumbnailimage(int `$width`, int `$height`): Gmagick

固定サイズのサムネイルを作成します。 まず画像のサイズを拡大あるいは縮小し、指定した範囲を中心から切り取ります。

### パラメータ

`width`
  サムネイルの幅。
`height`
  サムネイルの高さ。

### 戻り値

切り取った Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::current

(PECL gmagick >= Unknown)

Gmagick::current — 現在の Gmagick オブジェクトへの参照を返す

### 説明

public function Gmagick::current(): Gmagick

現在の gmagick オブジェクトへの参照を返し、 画像ポインタを正しいシーケンスに設定します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に自分自身を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::cyclecolormapimage

(PECL gmagick >= Unknown)

Gmagick::cyclecolormapimage — 画像のカラーマップを移動する

### 説明

public function Gmagick::cyclecolormapimage(int `$displace`): Gmagick

位置番号を指定して、画像のカラーマップを移動します。 カラーマップを何度か回転させると、サイケデリックな効果が得られます。

### パラメータ

`displace`
  カラーマップを移動させる量。

### 戻り値

成功した場合に自分自身を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::deconstructimages

(PECL gmagick >= Unknown)

Gmagick::deconstructimages — 画像間の特定のピクセルの差を返す

### 説明

public function Gmagick::deconstructimages(): Gmagick

各画像をシーケンス内の次の画像と比較し、 最大の境界範囲を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

新しい Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::despeckleimage

(PECL gmagick >= Unknown)

Gmagick::despeckleimage — 画像内のスペックルノイズを軽減する

### 説明

public function Gmagick::despeckleimage(): Gmagick

画像内のスペックルノイズを軽減します。ただし元画像の輪郭は保持します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

スペックルノイズを軽減した Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

### 例

例1 Gmagick::despeckleimage() の例

    <?php
    /* ... */
    ?>

上の例の出力は、 たとえば以下のようになります。

    ...

# Gmagick::destroy

(PECL gmagick >= Unknown)

Gmagick::destroy — Gmagick オブジェクトを破棄する

### 説明

public function Gmagick::destroy(): bool

Gmagick オブジェクトを破棄し、 関連するリソースをすべて解放します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::drawimage

(PECL gmagick >= Unknown)

Gmagick::drawimage — 現在の画像上の GmagickDraw オブジェクトをレンダリングする

### 説明

public function Gmagick::drawimage(GmagickDraw `$GmagickDraw`): Gmagick

現在の画像上の GmagickDraw オブジェクトをレンダリングします。

### パラメータ

`GmagickDraw`
  画像をレンダリングする描画操作。

### 戻り値

描かれた Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::edgeimage

(PECL gmagick >= Unknown)

Gmagick::edgeimage — 画像の輪郭を強調する

### 説明

public function Gmagick::edgeimage(float `$radius`): Gmagick

指定した半径の畳み込みフィルタを使用して、画像の輪郭を強調します。 radius に 0 を設定すると自動選択となります。

### パラメータ

`radius`
  操作の半径。

### 戻り値

輪郭を強調した Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::embossimage

(PECL gmagick >= Unknown)

Gmagick::embossimage — グレースケール画像に三次元効果を施して返す

### 説明

public function Gmagick::embossimage(float `$radius`, float `$sigma`): Gmagick

グレースケール画像に三次元効果を施したものを返します。 指定した半径と標準偏差 (シグマ) によるガウス演算によって画像を畳み込みます。 意味のある結果を得るには、半径がシグマより大きくなければなりません。 radius に 0 を指定すると、適切な半径を自動的に設定します。

### パラメータ

`radius`
  効果の半径。
`sigma`
  効果のシグマ。

### 戻り値

エンボス処理した Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::enhanceimage

(PECL gmagick >= Unknown)

Gmagick::enhanceimage — ノイジーな画像の品質を向上させる

### 説明

public function Gmagick::enhanceimage(): Gmagick

デジタルフィルタを適用して、ノイジーな画像の品質を向上させます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

品質を向上させた Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::equalizeimage

(PECL gmagick >= Unknown)

Gmagick::equalizeimage — 画像ヒストグラムを均等化する

### 説明

public function Gmagick::equalizeimage(): Gmagick

画像ヒストグラムを均等化します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

均等化した Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::flipimage

(PECL gmagick >= Unknown)

Gmagick::flipimage — 垂直方向に反転した画像を作成する

### 説明

public function Gmagick::flipimage(): Gmagick

中心の x 軸を基準してピクセルを反転させ、垂直方向のミラー画像を作成します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

垂直反転した Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

### 参考

- Gmagick::flopimage() - 水平方向に反転した画像を作成する

# Gmagick::flopimage

(PECL gmagick >= Unknown)

Gmagick::flopimage — 水平方向に反転した画像を作成する

### 説明

public function Gmagick::flopimage(): Gmagick

中心の y 軸を基準してピクセルを反転させ、水平方向のミラー画像を作成します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

垂直反転した Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

### 参考

- Gmagick::flipimage() - 垂直方向に反転した画像を作成する

# Gmagick::frameimage

(PECL gmagick >= Unknown)

Gmagick::frameimage — 三次元の枠線をシミュレートする

### 説明

public function 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::gammaimage

(PECL gmagick >= Unknown)

Gmagick::gammaimage — 画像をガンマ補正する

### 説明

public function Gmagick::gammaimage(float `$gamma`): Gmagick

画像をガンマ補正します。同じ画像でも、 異なるデバイス上で見ると見た目が変わることがあります。 これは、画面上に画像の輝度を表現する方法がことなるためです。 赤、緑、青の各チャネルに個別のガンマレベルを指定するか、 あるいはすべてのチャネルに共通のガンマレベルを指定します。 値の典型的な範囲は、0.8 から 2.3 の間となります。

### パラメータ

`gamma`
  ガンマ補正の量。

### 戻り値

ガンマ補正した Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getcopyright

(PECL gmagick >= Unknown)

Gmagick::getcopyright — GraphicsMagick API の著作権情報を文字列で返す

### 説明

public function Gmagick::getcopyright(): string

GraphicsMagick API の著作権情報を文字列で返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

GraphicsMagick および Magickwand C API の著作権情報を含む文字列を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getfilename

(PECL gmagick >= Unknown)

Gmagick::getfilename — 画像シーケンスに関連付けられたファイル名を取得する

### 説明

public function Gmagick::getfilename(): string

画像シーケンスに関連付けられたファイル名を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に文字列を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimagebackgroundcolor

(PECL gmagick >= Unknown)

Gmagick::getimagebackgroundcolor — 画像の背景色を返す

### 説明

public function Gmagick::getimagebackgroundcolor(): GmagickPixel

画像の背景色を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像の背景色を設定した GmagickPixel を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimageblueprimary

(PECL gmagick >= Unknown)

Gmagick::getimageblueprimary — 青が一番強い点を返す

### 説明

public function Gmagick::getimageblueprimary(): array

青が一番強い点を返します。

### パラメータ

`x`
  青が一番強い点の x 座標。
`y`
  青が一番強い点の y 座標。

### 戻り値

"x" 座標および "y" 座標を含む配列を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimagebordercolor

(PECL gmagick >= Unknown)

Gmagick::getimagebordercolor — 画像の前景色を返す

### 説明

public function Gmagick::getimagebordercolor(): GmagickPixel

画像の前景色を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像の前景色を表す GmagickPixel オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimagechanneldepth

(PECL gmagick >= Unknown)

Gmagick::getimagechanneldepth — 特定の画像チャネルの深度を返す

### 説明

public function Gmagick::getimagechanneldepth(int `$channel_type`): int

特定の画像チャネルの深度を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像チャネルの深度を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimagecolors

(PECL gmagick >= Unknown)

Gmagick::getimagecolors — 指定した色マップインデックスの色を返す

### 説明

public function Gmagick::getimagecolors(): int

指定した色マップインデックスの色を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像内の色の数を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimagecolorspace

(PECL gmagick >= Unknown)

Gmagick::getimagecolorspace — 画像の色空間を取得する

### 説明

public function Gmagick::getimagecolorspace(): int

画像の色空間を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

色空間を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimagecompose

(PECL gmagick >= Unknown)

Gmagick::getimagecompose — 画像の合成演算子を返す

### 説明

public function Gmagick::getimagecompose(): int

画像に関連付けられている合成演算子を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像に関連付けられている合成演算子を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimagedelay

(PECL gmagick >= Unknown)

Gmagick::getimagedelay — 画像の遅延を取得する

### 説明

public function Gmagick::getimagedelay(): int

画像の遅延を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像の遅延を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimagedepth

(PECL gmagick >= Unknown)

Gmagick::getimagedepth — 画像の深度を取得する

### 説明

public function Gmagick::getimagedepth(): int

画像の深度を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像の深度を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimagedispose

(PECL gmagick >= Unknown)

Gmagick::getimagedispose — 画像の配置方法を取得する

### 説明

public function Gmagick::getimagedispose(): int

画像の配置方法を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像の配置方法を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimageextrema

(PECL gmagick >= Unknown)

Gmagick::getimageextrema — 画像の極値を取得する

### 説明

public function Gmagick::getimageextrema(): array

画像の極値を取得します。 "min" および "max" というキーを持つ連想配列を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

"min" および "max" というキーを持つ連想配列を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimagefilename

(PECL gmagick >= Unknown)

Gmagick::getimagefilename — シーケンス内の特定の画像のファイル名を返す

### 説明

public function Gmagick::getimagefilename(): string

シーケンス内の特定の画像のファイル名を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像のファイル名を文字列で返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimageformat

(PECL gmagick >= Unknown)

Gmagick::getimageformat — シーケンス内の特定の画像のフォーマットを返す

### 説明

public function Gmagick::getimageformat(): string

シーケンス内の特定の画像のフォーマットを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合は画像のフォーマットを文字列で返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimagegamma

(PECL gmagick >= Unknown)

Gmagick::getimagegamma — 画像のガンマを取得する

### 説明

public function Gmagick::getimagegamma(): float

画像のガンマを取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合にガンマを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimagegreenprimary

(PECL gmagick >= Unknown)

Gmagick::getimagegreenprimary — 緑が一番強い点を返す

### 説明

public function Gmagick::getimagegreenprimary(): array

緑が一番強い点を返します。"x" および "y" というキーを持つ配列を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に "x" および "y" というキーを持つ配列を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimageheight

(PECL gmagick >= Unknown)

Gmagick::getimageheight — 画像の高さを返す

### 説明

public function Gmagick::getimageheight(): int

画像の高さを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像の高さをピクセル数で返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimagehistogram

(PECL gmagick >= Unknown)

Gmagick::getimagehistogram — 画像のヒストグラムを取得する

### 説明

public function Gmagick::getimagehistogram(): array

画像のヒストグラムを GmagickPixel オブジェクトの配列で返します。 エラーが起きた場合は GmagickException をスローします。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像のヒストグラムを GmagickPixel オブジェクトの配列で返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimageindex

(PECL gmagick >= Unknown)

Gmagick::getimageindex — 現在アクティブな画像のインデックスを取得する

### 説明

public function Gmagick::getimageindex(): int

Gmagick オブジェクト内で現在アクティブな画像のインデックスを取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

現在アクティブな画像のインデックスを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimageinterlacescheme

(PECL gmagick >= Unknown)

Gmagick::getimageinterlacescheme — 画像のインターレース手法を取得する

### 説明

public function Gmagick::getimageinterlacescheme(): int

画像のインターレース手法を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に画像のインターレース手法を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimageiterations

(PECL gmagick >= Unknown)

Gmagick::getimageiterations — 画像の反復を取得する

### 説明

public function Gmagick::getimageiterations(): int

画像の反復を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像の反復を表す整数値を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimagematte

(PECL gmagick >= Unknown)

Gmagick::getimagematte — 画像がマットチャネルを持っているかどうかを調べる

### 説明

public function Gmagick::getimagematte(): int

画像がマットチャネルを持っている場合に `true`、 そうでない場合に `false` を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像がマットチャネルを持っている場合に `true`、 そうでない場合に `false` を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimagemattecolor

(PECL gmagick >= Unknown)

Gmagick::getimagemattecolor — 画像のマット色を返す

### 説明

public function Gmagick::getimagemattecolor(): GmagickPixel

成功した場合に GmagickPixel オブジェクトを返します。エラー時に GmagickException をスローします。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に GmagickPixel オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimageprofile

(PECL gmagick >= Unknown)

Gmagick::getimageprofile — 指定した名前の画像プロファイルを返す

### 説明

public function Gmagick::getimageprofile(string `$name`): string

指定した名前の画像プロファイルを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像プロファイルを含む文字列を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimageredprimary

(PECL gmagick >= Unknown)

Gmagick::getimageredprimary — 赤が一番強い点を返す

### 説明

public function Gmagick::getimageredprimary(): array

赤が一番強い点を返します。"x" および "y" というキーを持つ配列を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

赤が一番強い点を "x" および "y" というキーを持つ配列で返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimagerenderingintent

(PECL gmagick >= Unknown)

Gmagick::getimagerenderingintent — 画像のレンダリング方向を取得する

### 説明

public function Gmagick::getimagerenderingintent(): int

画像のレンダリング方向を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像のレンダリング方向を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimageresolution

(PECL gmagick >= Unknown)

Gmagick::getimageresolution — 画像の X 方向と Y 方向の解像度を取得する

### 説明

public function Gmagick::getimageresolution(): array

解像度を配列で取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

解像度を配列で返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimagescene

(PECL gmagick >= Unknown)

Gmagick::getimagescene — 画像のシーンを取得する

### 説明

public function Gmagick::getimagescene(): int

画像のシーンを取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像のシーンを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimagesignature

(PECL gmagick >= Unknown)

Gmagick::getimagesignature — SHA-256 メッセージダイジェストを生成する

### 説明

public function Gmagick::getimagesignature(): string

画像ピクセルストリームの SHA-256 メッセージダイジェストを生成します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

そのファイルの SHA-256 ハッシュを文字列で返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimagetype

(PECL gmagick >= Unknown)

Gmagick::getimagetype — 画像の型を取得する

### 説明

public function Gmagick::getimagetype(): int

画像の型を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像の型を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimageunits

(PECL gmagick >= Unknown)

Gmagick::getimageunits — 画像の解像度の単位を取得する

### 説明

public function Gmagick::getimageunits(): int

画像の解像度の単位を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像の解像度の単位を返します。

# Gmagick::getimagewhitepoint

(PECL gmagick >= Unknown)

Gmagick::getimagewhitepoint — 色度が白い点を返す

### 説明

public function Gmagick::getimagewhitepoint(): array

色度が白い点を返します。 "x" および "y" というキーを持つ連想配列となります。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

色度が白い点を返します。 "x" および "y" というキーを持つ連想配列となります。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getimagewidth

(PECL gmagick >= Unknown)

Gmagick::getimagewidth — 画像の幅を返す

### 説明

public function Gmagick::getimagewidth(): int

画像の幅を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像の幅を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getpackagename

(PECL gmagick >= Unknown)

Gmagick::getpackagename — GraphicsMagick パッケージ名を返す

### 説明

public function Gmagick::getpackagename(): string

GraphicsMagick パッケージ名を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

GraphicsMagick パッケージ名を文字列で返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getquantumdepth

(PECL gmagick >= Unknown)

Gmagick::getquantumdepth — Gmagick quantum depth を返す

### 説明

public function Gmagick::getquantumdepth(): array

Gmagick quantum depth を文字列で返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Gmagick quantum depth を文字列で返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getreleasedate

(PECL gmagick >= Unknown)

Gmagick::getreleasedate — GraphicsMagick のリリース日を返す

### 説明

public function Gmagick::getreleasedate(): string

GraphicsMagick のリリース日を文字列で返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

GraphicsMagick のリリース日を文字列で返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getsamplingfactors

(PECL gmagick >= Unknown)

Gmagick::getsamplingfactors — 水平方向および垂直方向のサンプリング係数を取得する

### 説明

public function Gmagick::getsamplingfactors(): array

水平方向および垂直方向のサンプリング係数を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像の水平方向および垂直方向のサンプリング係数を含む連想配列を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getsize

(PECL gmagick >= Unknown)

Gmagick::getsize — Gmagick オブジェクトのサイズを取得する

### 説明

public function Gmagick::getsize(): array

Gmagick オブジェクトのサイズを返します。 "columns" および "rows" というキーを持つ連想配列となります。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Gmagick オブジェクトのサイズを返します。 "columns" および "rows" というキーを持つ連想配列となります。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::getversion

(PECL gmagick >= Unknown)

Gmagick::getversion — GraphicsMagick API のバージョンを返す

### 説明

public function Gmagick::getversion(): array

GraphicsMagick API のバージョンを文字列と数値で返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

GraphicsMagick API のバージョンを文字列と数値で返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::hasnextimage

(PECL gmagick >= Unknown)

Gmagick::hasnextimage — オブジェクトが次の画像を保持しているかどうかを調べる

### 説明

public function Gmagick::hasnextimage(): mixed

リスト内でひとつ先に進んだときにまだオブジェクトが画像を保持していれば `true` を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

リスト内でひとつ先に進んだときにまだオブジェクトが画像を保持していれば `true`、していなければ `false` を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::haspreviousimage

(PECL gmagick >= Unknown)

Gmagick::haspreviousimage — オブジェクトが前の画像を保持しているかどうかを調べる

### 説明

public function Gmagick::haspreviousimage(): mixed

リスト内で逆方向にひとつ進んだときにまだオブジェクトが画像を保持していれば `true` を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

リスト内で逆方向にひとつ進んだときにまだオブジェクトが画像を保持していれば `true`、していなければ `false` を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::implodeimage

(PECL gmagick >= Unknown)

Gmagick::implodeimage — 新しい画像をコピーとして作成する

### 説明

public function Gmagick::implodeimage(float `$radius`): mixed

既存の画像をコピーして新しい画像を作成します。 既存の画像のピクセルを、指定したパーセンテージで "内破" します。

### パラメータ

`radius`
  内破処理の半径。

### 戻り値

内破した Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::labelimage

(PECL gmagick >= Unknown)

Gmagick::labelimage — ラベルを画像に追加する

### 説明

public function Gmagick::labelimage(string `$label`): mixed

ラベルを画像に追加します。

### パラメータ

`label`
  追加するラベル。

### 戻り値

ラベルを追加した Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::levelimage

(PECL gmagick >= Unknown)

Gmagick::levelimage — 画像のレベルを調節する

### 説明

public function Gmagick::levelimage(
float `$blackPoint`,
float `$gamma`,
float `$whitePoint`,
int `$channel` = Gmagick::CHANNEL_DEFAULT
): mixed

画像のレベルを調整します。 指定した白と黒の範囲にある色を、利用可能な色の範囲全体に拡大します。 黒の点、中間点、白の点をパラメータで指定します。 黒の点は、画像の中で一番暗い色を表します。 これより暗い色の点はゼロに設定されます。 中間点は、画像に適用するガンマ補正を指定します。 黒の点は、画像の中で一番明るい色を表します。 これより明るい色の点は最大値に設定されます。

### パラメータ

`blackPoint`
  画像の黒の点。
`gamma`
  ガンマ値。
`whitePoint`
  画像の白の点。
`channel`
  チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

### 戻り値

画像のレベルを調節した Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::magnifyimage

(PECL gmagick >= Unknown)

Gmagick::magnifyimage — 画像を二倍に比例拡大する

### 説明

public function Gmagick::magnifyimage(): mixed

画像を元のサイズの二倍に比例拡大します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

拡大した Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::mapimage

(PECL gmagick >= Unknown)

Gmagick::mapimage — 画像の色を、参照画像の中の最も近い色に置き換える

### 説明

public function Gmagick::mapimage(gmagick `$gmagick`, bool `$dither`): Gmagick

画像の色を、参照画像の中の最も近い色に置き換えます。

### パラメータ

`gmagick`
  参照する画像。
`dither`
  ゼロ以外の整数値を設定して、マップした画像をディザリングします。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::medianfilterimage

(PECL gmagick >= Unknown)

Gmagick::medianfilterimage — デジタルフィルタを適用する

### 説明

public function Gmagick::medianfilterimage(float `$radius`): void

デジタルフィルタを適用してノイジーな画像の品質を向上させます。 各ピクセルの内容を、radius で定義した近傍ピクセルの中央値で置き換えます。

### パラメータ

`radius`
  近傍ピクセルの半径。

### 戻り値

メジアンフィルタを適用した Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::minifyimage

(PECL gmagick >= Unknown)

Gmagick::minifyimage — 画像をその半分のサイズに比例縮小する

### 説明

public function Gmagick::minifyimage(): Gmagick

画像のサイズを元の半分に比例縮小します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::modulateimage

(PECL gmagick >= Unknown)

Gmagick::modulateimage — 明度、彩度、色相を制御する

### 説明

public function 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::motionblurimage

(PECL gmagick >= Unknown)

Gmagick::motionblurimage — モーションブラーをシミュレートする

### 説明

public function Gmagick::motionblurimage(float `$radius`, float `$sigma`, float `$angle`): Gmagick

モーションブラーをシミュレートします。 指定した半径と標準偏差 (シグマ) によるガウス演算によって画像を畳み込みます。 意味のある結果を得るには、半径がシグマより大きくなければなりません。 radius に 0 を指定すると、 Gmagick::motionblurimage() が適切な半径を自動的に設定します。 angle にはぼかしをかける角度を指定します。

### パラメータ

`radius`
  ガウス演算の半径。ピクセル単位で指定し、中心は計算に入れません。
`sigma`
  ガウス演算の標準偏差。ピクセル単位で指定します。
`angle`
  この角度で効果を適用します。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::newimage

(PECL gmagick >= Unknown)

Gmagick::newimage — 新しい画像を作成する

### 説明

public function Gmagick::newimage(
int `$width`,
int `$height`,
string `$background`,
string `$format` = ?
): Gmagick

新しい画像を作成し、背景色を設定します。

### パラメータ

`width`
  新しい画像の幅。
`height`
  新しい画像の高さ。
`background`
  この画像で使う背景色 (浮動小数点数)。
`format`
  画像フォーマット。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::nextimage

(PECL gmagick >= Unknown)

Gmagick::nextimage — 次の画像に移動する

### 説明

public function Gmagick::nextimage(): bool

画像リスト内の次の画像を Gmagick オブジェクトに関連付けます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::normalizeimage

(PECL gmagick >= Unknown)

Gmagick::normalizeimage — カラー画像のコントラストを強調する

### 説明

public function Gmagick::normalizeimage(int `$channel` = ?): Gmagick

カラー画像のコントラストを強調します。 ピクセルの色を、とりうる値の範囲全体に拡張します。

### パラメータ

`channel`
  どのチャネルを正規化するか。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::oilpaintimage

(PECL gmagick >= Unknown)

Gmagick::oilpaintimage — 油絵をシミュレートする

### 説明

public function Gmagick::oilpaintimage( float `$radius` ): Gmagick

油絵風の効果を施すフィルタを適用します。 各ピクセルが、指定した半径内の周囲の中で最もよくあらわれる色に置き換えられます。

### パラメータ

`radius`
  近傍円の半径。

### 戻り値

成功した場合に Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::previousimage

(PECL gmagick >= Unknown)

Gmagick::previousimage — オブジェクト内の前の画像に移動する

### 説明

public function Gmagick::previousimage(): bool

画像リスト内の前の画像を Gmagick オブジェクトに関連付けます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::profileimage

(PECL gmagick >= Unknown)

Gmagick::profileimage — 画像のプロファイルを追加あるいは削除する

### 説明

public function Gmagick::profileimage(string `$name`, string `$profile`): Gmagick

ICC、IPTC あるいは汎用のプロファイルを画像に追加あるいは削除します。 profile が `null` の場合は画像からプロファイルを削除し、 それ以外の場合は追加します。 name に `*`、profile に `null` を指定すると、画像からすべてのプロパティを削除します。

### パラメータ

`name`
  追加あるいは削除するプロファイルの名前。ICC、IPTC、あるいは generic。
`profile`
  プロファイル。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::quantizeimage

(PECL gmagick >= Unknown)

Gmagick::quantizeimage — 参照画像内の色を解析する

### 説明

public function 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::quantizeimages

(PECL gmagick >= Unknown)

Gmagick::quantizeimages — 画像シーケンス内の色を解析する

### 説明

public function 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::queryfontmetrics

(PECL gmagick >= Unknown)

Gmagick::queryfontmetrics — フォントメトリクスを表す配列を返す

### 説明

public function Gmagick::queryfontmetrics(GmagickDraw `$draw`, string `$text`): array

MagickQueryFontMetrics() は、フォントメトリクスを表す多次元配列を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::queryfonts

(PECL gmagick >= Unknown)

Gmagick::queryfonts — 設定したフォントを返す

### 説明

public function Gmagick::queryfonts(string `$pattern` = "*"): array

設定したフォントを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::queryformats

(PECL gmagick >= Unknown)

Gmagick::queryformats — Gmagick がサポートするフォーマットを返す

### 説明

public function Gmagick::queryformats(string `$pattern` = "*"): array

Gmagick がサポートするフォーマットを返します。

### パラメータ

`pattern`
  パターンを含む文字列へのポインタを指定します。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::radialblurimage

(PECL gmagick >= Unknown)

Gmagick::radialblurimage — 画像にラジアルブラーを施す

### 説明

public function Gmagick::radialblurimage(float `$angle`, int `$channel` = Gmagick::CHANNEL_DEFAULT): Gmagick

画像にラジアルブラーを施します。

### パラメータ

`angle`
  ラジアルブラーの角度。
`channel`
  関連するチャネル。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::raiseimage

(PECL gmagick >= Unknown)

Gmagick::raiseimage — 三次元のボタン風の効果をシミュレートする

### 説明

public function 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::read

(PECL gmagick >= Unknown)

Gmagick::read — ファイルから画像を読み込む

### 説明

public function Gmagick::read(string `$filename`): Gmagick

ファイルから画像を読み込みます。

### パラメータ

`filename`
  画像ファイル名。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::readimage

(PECL gmagick >= Unknown)

Gmagick::readimage — ファイルから画像を読み込む

### 説明

public function Gmagick::readimage(string `$filename`): Gmagick

ファイルから画像を読み込みます。

### パラメータ

`filename`
  画像ファイル名。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::readimageblob

(PECL gmagick >= Unknown)

Gmagick::readimageblob — バイナリ文字列から画像を読み込む

### 説明

public function Gmagick::readimageblob(string `$imageContents`, string `$filename` = ?): Gmagick

バイナリ文字列から画像を読み込みます。

### パラメータ

`imageContents`
  画像の内容。
`filename`
  画像ファイル名。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::readimagefile

(PECL gmagick >= Unknown)

Gmagick::readimagefile — オープンしているファイルハンドルから画像を読み込む

### 説明

public function Gmagick::readimagefile(resource `$fp`, string `$filename` = ?): Gmagick

オープンしているファイルハンドルから画像を読み込みます。

### パラメータ

`fp`
  ファイルディスクリプタ。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::reducenoiseimage

(PECL gmagick >= Unknown)

Gmagick::reducenoiseimage — 画像の輪郭をなめらかにする

### 説明

public function Gmagick::reducenoiseimage(float `$radius`): Gmagick

画像の輪郭をなめらかにします。縁の情報は保持します。 各ピクセルの内容を近傍の一番近い値で置き換えるというアルゴリズムです。 近傍は半径で定義します。radius に 0 を指定すると、 Gmagick::reducenoiseimage() が適切な半径を自動的に設定します。

### パラメータ

`radius`
  近傍ピクセルの半径。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::removeimage

(PECL gmagick >= Unknown)

Gmagick::removeimage — 画像リストから画像を削除する

### 説明

public function Gmagick::removeimage(): Gmagick

画像リストから画像を削除します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::removeimageprofile

(PECL gmagick >= Unknown)

Gmagick::removeimageprofile — 指定した名前の画像プロファイルを削除して返す

### 説明

public function Gmagick::removeimageprofile(string `$name`): string

指定した名前の画像プロファイルを削除して返します。

### パラメータ

`name`
  返すプロファイルの名前。ICC、IPTC あるいは generic。

### 戻り値

指定した名前のプロファイルを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::resampleimage

(PECL gmagick >= Unknown)

Gmagick::resampleimage — 画像を指定した解像度にリサンプリングする

### 説明

public function Gmagick::resampleimage(
float `$xResolution`,
float `$yResolution`,
int `$filter`,
float `$blur`
): Gmagick

画像を指定した解像度にリサンプリングします。

### パラメータ

`xResolution`
  新しい画像の x 方向の解像度。
`yResolution`
  新しい画像の y 方向の解像度。
`filter`
  利用するフィルタ。
`blur`
  blur 要素。> 1 はぼやけた状態、< 1 はシャープな状態を表します。

### 戻り値

成功した場合に Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::resizeimage

(PECL gmagick >= Unknown)

Gmagick::resizeimage — 画像のサイズを変更する

### 説明

public function Gmagick::resizeimage(
int `$width`,
int `$height`,
int `$filter`,
float `$blur`,
bool `$fit` = `false`
): Gmagick

指定した大きさとフィルタで、画像のサイズを変更します。

### パラメータ

`width`
  画像の幅。
`height`
  画像の高さ。
`filter`
  利用するフィルタ。
`blur`
  blur 要素。> 1 はぼやけた状態、< 1 はシャープな状態を表します。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::rollimage

(PECL gmagick >= Unknown)

Gmagick::rollimage — 画像を補正する

### 説明

public function Gmagick::rollimage(int `$x`, int `$y`): Gmagick

x および y を指定して画像を補正します。

### パラメータ

`x`
  x オフセット。
`y`
  y オフセット。

### 戻り値

成功した場合に Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::rotateimage

(PECL gmagick >= Unknown)

Gmagick::rotateimage — 画像を回転する

### 説明

public function Gmagick::rotateimage(mixed `$color`, float `$degrees`): Gmagick

指定した角度だけ画像を回転させます。回転によって生じる空き領域は、 背景色で埋められます。

### パラメータ

`color`
  背景色。
`degrees`
  画像を回転させる度数。

### 戻り値

成功した場合に Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::scaleimage

(PECL gmagick >= Unknown)

Gmagick::scaleimage — 画像のサイズを変更する

### 説明

public function Gmagick::scaleimage(int `$width`, int `$height`, bool `$fit` = `false`): Gmagick

画像のサイズを指定した大きさに変更します。 パラメータに 0 を指定すると、そのパラメータを自動的に計算します。

### パラメータ

`width`
  変更後の画像の幅。
`height`
  変更後の画像の高さ。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::separateimagechannel

(PECL gmagick >= Unknown)

Gmagick::separateimagechannel — 画像からチャネルを分離する

### 説明

public function Gmagick::separateimagechannel(int `$channel`): Gmagick

画像からチャネルを分離し、グレースケール画像を返します。 channel には、画像の各ピクセルの特定の色コンポーネントを指定します。

### パラメータ

`channel`
  チャンネル 定数のうちの一つ。 (`Gmagick::CHANNEL_*`)

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setCompressionQuality

(No version information available, might only be in Git)

Gmagick::setCompressionQuality — オブジェクトのデフォルトの圧縮クオリティを設定する

### 説明

function Gmagick::setCompressionQuality( int `$quality` ): Gmagick

オブジェクトのデフォルトの圧縮クオリティを設定します。

### パラメータ

`quality`
  GraphicsMagick のデフォルト値は 75 です。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

### 例

例1 Gmagick::setCompressionQuality()

    <?php
    $gm = new Gmagick();
    $gm->read("magick:rose");
    $gm->setCompressionQuality(2);
    ?>

# Gmagick::setfilename

(PECL gmagick >= Unknown)

Gmagick::setfilename — 画像を読み書きする前にファイル名を設定する

### 説明

public function Gmagick::setfilename(string `$filename`): Gmagick

画像を読み書きする前にファイル名を設定します。

### パラメータ

`filename`
  画像ファイル名。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setimagebackgroundcolor

(PECL gmagick >= Unknown)

Gmagick::setimagebackgroundcolor — 画像の背景色を設定する

### 説明

public function Gmagick::setimagebackgroundcolor(GmagickPixel `$color`): Gmagick

画像の背景色を設定します。

### パラメータ

`color`
  画像の背景色。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setimageblueprimary

(PECL gmagick >= Unknown)

Gmagick::setimageblueprimary — 青が一番強い点を設定する

### 説明

public function Gmagick::setimageblueprimary(float `$x`, float `$y`): Gmagick

青が一番強い点を設定します。

### パラメータ

`x`
  青が一番強い点の x 座標。
`y`
  青が一番強い点の y 座標。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setimagebordercolor

(PECL gmagick >= Unknown)

Gmagick::setimagebordercolor — 画像の枠線の色を設定する

### 説明

public function Gmagick::setimagebordercolor(GmagickPixel `$color`): Gmagick

画像の枠線の色を設定します。

### パラメータ

`color`
  画像の前景色。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setimagechanneldepth

(PECL gmagick >= Unknown)

Gmagick::setimagechanneldepth — 特定の画像チャネルの深度を設定する

### 説明

public function Gmagick::setimagechanneldepth(int `$channel`, int `$depth`): Gmagick

特定の画像チャネルの深度を設定します。

### パラメータ

`channel`
  チャンネル 定数のうちの一つ。 (`Gmagick::CHANNEL_*`)
`depth`
  深度を表すビット数。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setimagecolorspace

(PECL gmagick >= Unknown)

Gmagick::setimagecolorspace — 画像の色空間を設定する

### 説明

public function Gmagick::setimagecolorspace(int `$colorspace`): Gmagick

画像の色空間を設定します。

### パラメータ

`colorspace`
  色空間 定数のうちの一つ。 (`Gmagick::COLORSPACE_*`)

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setimagecompose

(PECL gmagick >= Unknown)

Gmagick::setimagecompose — 画像の合成演算子を設定する

### 説明

public function Gmagick::setimagecompose(int `$composite`): Gmagick

画像の合成演算子を設定します。

### パラメータ

`composite`
  画像の合成演算子。

### 戻り値

成功した場合に Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setimagedelay

(PECL gmagick >= Unknown)

Gmagick::setimagedelay — 画像の遅延を設定する

### 説明

public function Gmagick::setimagedelay(int `$delay`): Gmagick

画像の遅延を設定します。

### パラメータ

`delay`
  画像の遅延を 1/100 秒単位で指定します。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setimagedepth

(PECL gmagick >= Unknown)

Gmagick::setimagedepth — 画像の深度を設定する

### 説明

public function Gmagick::setimagedepth(int `$depth`): Gmagick

画像の深度を設定します。

### パラメータ

`depth`
  画像の深度 (ビット)。8、16 あるいは 32。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setimagedispose

(PECL gmagick >= Unknown)

Gmagick::setimagedispose — 画像の配置方法を設定する

### 説明

public function Gmagick::setimagedispose(int `$disposeType`): Gmagick

画像の配置方法を設定します。

### パラメータ

`disposeType`
  画像の配置方法。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setimagefilename

(PECL gmagick >= Unknown)

Gmagick::setimagefilename — シーケンス内の特定の画像のファイル名を設定する

### 説明

public function Gmagick::setimagefilename(string `$filename`): Gmagick

シーケンス内の特定の画像のファイル名を設定します。

### パラメータ

`filename`
  画像ファイル名。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setimageformat

(PECL gmagick >= Unknown)

Gmagick::setimageformat — 特定の画像のフォーマットを設定する

### 説明

public function Gmagick::setimageformat(string `$imageFormat`): Gmagick

シーケンス内の特定の画像のフォーマットを設定します。

### パラメータ

`imageFormat`
  画像のフォーマット。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setimagegamma

(PECL gmagick >= Unknown)

Gmagick::setimagegamma — 画像のガンマを設定する

### 説明

public function Gmagick::setimagegamma(float `$gamma`): Gmagick

画像のガンマを設定します。

### パラメータ

`gamma`
  画像のガンマ。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setimagegreenprimary

(PECL gmagick >= Unknown)

Gmagick::setimagegreenprimary — 緑が一番強い点を設定する

### 説明

public function Gmagick::setimagegreenprimary(float `$x`, float `$y`): Gmagick

緑が一番強い点を設定します。

### パラメータ

`x`
  緑が一番強い点の x 座標。
`y`
  緑が一番強い点の y 座標。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setimageindex

(PECL gmagick >= Unknown)

Gmagick::setimageindex — 画像リスト内でのイテレータの位置を、index パラメータで指定した場所に設定する

### 説明

public function Gmagick::setimageindex(int `$index`): Gmagick

画像リスト内でのイテレータの位置を、index パラメータで指定した場所に設定します。

### パラメータ

`index`
  シーン番号。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setimageinterlacescheme

(PECL gmagick >= Unknown)

Gmagick::setimageinterlacescheme — 画像のインターレース手法を設定する

### 説明

public function Gmagick::setimageinterlacescheme(int `$interlace`): Gmagick

画像のインターレース手法を設定します。

### パラメータ

`interlace`
  インターレース 定数のうちの一つ。 (`Gmagick::INTERLACE_*`)

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setimageiterations

(PECL gmagick >= Unknown)

Gmagick::setimageiterations — 画像の反復を設定する

### 説明

public function Gmagick::setimageiterations(int `$iterations`): Gmagick

画像の反復を設定します。

### パラメータ

`iterations`
  画像の遅延を 1/100 秒単位で指定します。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setimageprofile

(PECL gmagick >= Unknown)

Gmagick::setimageprofile — 指定した名前の画像プロファイルを Gmagick オブジェクトに追加する

### 説明

public function Gmagick::setimageprofile(string `$name`, string `$profile`): Gmagick

指定した名前の画像プロファイルを Gmagick オブジェクトに追加します。 同じ名前のプロファイルが存在する場合は、それを置き換えます。 このメソッドは Gmagick::profileImage() メソッドとは異なり、 CMS カラープロファイルは適用しません。

### パラメータ

`name`
  追加あるいは削除するプロファイルの名前。ICC、IPTC あるいは generic。
`profile`
  プロファイル。

### 戻り値

成功した場合に Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setimageredprimary

(PECL gmagick >= Unknown)

Gmagick::setimageredprimary — 赤が一番強い点を設定する

### 説明

public function Gmagick::setimageredprimary(float `$x`, float `$y`): Gmagick

赤が一番強い点を設定します。

### パラメータ

`x`
  赤が一番強い点の x 座標。
`y`
  赤が一番強い点の y 座標。

### 戻り値

成功した場合に Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setimagerenderingintent

(PECL gmagick >= Unknown)

Gmagick::setimagerenderingintent — 画像のレンダリング方向を設定する

### 説明

public function Gmagick::setimagerenderingintent(int `$rendering_intent`): Gmagick

画像のレンダリング方向を設定します。

### パラメータ

`rendering_intent`
  レンダリング方向 の定数のうちの一つ。 (`Gmagick::RENDERINGINTENT_*`)

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setimageresolution

(PECL gmagick >= Unknown)

Gmagick::setimageresolution — 画像の解像度を設定する

### 説明

public function Gmagick::setimageresolution(float `$xResolution`, float `$yResolution`): Gmagick

画像の解像度を設定します。

### パラメータ

`xResolution`
  x 方向の解像度。
`yResolution`
  y 方向の解像度。

### 戻り値

成功した場合に Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setimagescene

(PECL gmagick >= Unknown)

Gmagick::setimagescene — 画像のシーンを設定する

### 説明

public function Gmagick::setimagescene(int `$scene`): Gmagick

画像のシーンを設定します。

### パラメータ

`scene`
  画像のシーン番号。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setimagetype

(PECL gmagick >= Unknown)

Gmagick::setimagetype — 画像の型を設定する

### 説明

public function Gmagick::setimagetype(int `$imgType`): Gmagick

画像の型を設定します。

### パラメータ

`imgType`
  画像の型 の定数のうちのひとつ。 (`Gmagick::IMGTYPE_*`)

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setimageunits

(PECL gmagick >= Unknown)

Gmagick::setimageunits — 画像の解像度の単位を設定する

### 説明

public function Gmagick::setimageunits(int `$resolution`): Gmagick

画像の解像度の単位を設定します。

### パラメータ

`resolution`
  画像の解像度の単位。Undefinedresolution、PixelsPerInchResolution あるいは PixelsPerCentimeterResolution。 解像度 の定数のうちの一つ。 (`Gmagick::RESOLUTION_*`)

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setimagewhitepoint

(PECL gmagick >= Unknown)

Gmagick::setimagewhitepoint — 画像の色度が白い点を設定する

### 説明

public function Gmagick::setimagewhitepoint(float `$x`, float `$y`): Gmagick

画像の色度が白い点を設定します。

### パラメータ

`x`
  白い点の x 座標。
`y`
  白い点の y 座標。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setsamplingfactors

(PECL gmagick >= Unknown)

Gmagick::setsamplingfactors — 画像のサンプリング係数を設定する

### 説明

public function Gmagick::setsamplingfactors(array `$factors`): Gmagick

画像のサンプリング係数を設定します。

### パラメータ

`factors`
  各色コンポーネントのサンプリング係数を表す float 型の値の配列 (RGB 順)。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::setsize

(PECL gmagick >= Unknown)

Gmagick::setsize — Gmagick オブジェクトのサイズを設定する

### 説明

public function Gmagick::setsize(int `$columns`, int `$rows`): Gmagick

Gmagick オブジェクトのサイズを設定します。 `Gmagick::COLORSPACE_RGB` や `Gmagick::COLORSPACE_GRAY`、 `Gmagick::COLORSPACE_CMYK` といった生の画像フォーマットを読み込む前に設定します。

### パラメータ

`columns`
  ピクセル数で指定する幅。
`rows`
  ピクセル数で指定する高さ。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::shearimage

(PECL gmagick >= Unknown)

Gmagick::shearimage — 平行四辺形を作成する

### 説明

public function 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::solarizeimage

(PECL gmagick >= Unknown)

Gmagick::solarizeimage — 画像にソラリゼーション効果を適用する

### 説明

public function Gmagick::solarizeimage(int `$threshold`): Gmagick

画像に特殊効果を施し、 印画紙の特定の箇所の露光時間を長くしたような画像になります。 threshold は 0 から QuantumRange までの値で、 ソラリゼーションの効き具合を指定します。

### パラメータ

`threshold`
  ソラリゼーションの効き具合を指定します。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::spreadimage

(PECL gmagick >= Unknown)

Gmagick::spreadimage — ブロック内の各ピクセルをランダムに移動する

### 説明

public function Gmagick::spreadimage(float `$radius`): Gmagick

radius パラメータで定義したブロック内の各ピクセルを、 ランダムに移動させます。

### パラメータ

`radius`
  この範囲の近くにあるランダムなピクセルを選びます。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::stripimage

(PECL gmagick >= Unknown)

Gmagick::stripimage — 画像からすべてのプロパティやコメントを除去する

### 説明

public function Gmagick::stripimage(): Gmagick

画像からすべてのプロパティやコメントを除去します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::swirlimage

(PECL gmagick >= Unknown)

Gmagick::swirlimage — 画像の中心から、ピクセルを渦巻状にする

### 説明

public function Gmagick::swirlimage(float `$degrees`): Gmagick

画像の中心から、ピクセルを渦巻状にします。 degrees は個々のピクセルが移動する弧の量を表します。 degrees を 1 から 360 まで変化させると、劇的な効果が得られます。

### パラメータ

`degrees`
  渦巻効果の程度。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::thumbnailimage

(PECL gmagick >= Unknown)

Gmagick::thumbnailimage — 画像のサイズを変更する

### 説明

public function Gmagick::thumbnailimage(int `$width`, int `$height`, bool `$fit` = `false`): Gmagick

画像のサイズを指定したものに変更し、関連付けられたプロパティをすべて削除します。 ウェブ上での表示に適した小さなサムネイル画像を作成します。 三番目のパラメータに `true` を指定すると、columns や rows にそれぞれの最大値を使用します。両方のパラメータが、 マッチするまであるいは指定したパラメータより小さくなるまで縮小されます。

### パラメータ

`width`
  画像の幅。
`height`
  画像の高さ。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::trimimage

(PECL gmagick >= Unknown)

Gmagick::trimimage — 画像の輪郭を削除する

### 説明

public function Gmagick::trimimage(float `$fuzz`): Gmagick

画像の背景色と同じ色の輪郭を削除します。

### パラメータ

`fuzz`
  デフォルトでは、対象の色は特定のピクセルの色とまったく同じでなければなりません。 しかし、ふたつの色が微妙に異なることもよくあります。 画像の fuzz メンバは、どの程度の色を「同じ色」とみなすかを表します。 このパラメータは、量の範囲の変化を表します。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

# Gmagick::write

(PECL gmagick >= Unknown)

Gmagick::write — Gmagick::writeimage() のエイリアス

### 説明

このメソッドは次のメソッドのエイリアスです。 Gmagick::writeimage()

# Gmagick::writeimage

(PECL gmagick >= Unknown)

Gmagick::writeimage — 画像を指定したファイル名で書き出す

### 説明

public function Gmagick::writeimage(string `$filename`, bool `$all_frames` = `false`): Gmagick

画像を指定したファイル名で書き出します。filename が `null` の場合は、 Gmagick::readimage() あるいは Gmagick::setimagefilename() で設定したファイル名で書き出します。

### パラメータ

`filename`
  画像ファイル名。

### 戻り値

Gmagick オブジェクトを返します。

### エラー / 例外

エラー時に GmagickException をスローします。

## 目次

- 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 クラス

(PECL gmagick >= Unknown)

## はじめに

## クラス概要

class GmagickDraw {
/* メソッド */
public function annotate(float `$x`, float `$y`, string `$text`): GmagickDraw
public function arc(
float `$sx`,
float `$sy`,
float `$ex`,
float `$ey`,
float `$sd`,
float `$ed`
): GmagickDraw
public function bezier(array `$coordinate_array`): GmagickDraw
public function ellipse(
float `$ox`,
float `$oy`,
float `$rx`,
float `$ry`,
float `$start`,
float `$end`
): GmagickDraw
public function getfillcolor(): GmagickPixel
public function getfillopacity(): float
public function getfont(): mixed
public function getfontsize(): float
public function getfontstyle(): int
public function getfontweight(): int
public function getstrokecolor(): GmagickPixel
public function getstrokeopacity(): float
public function getstrokewidth(): float
public function gettextdecoration(): int
public function gettextencoding(): mixed
public function line(
float `$sx`,
float `$sy`,
float `$ex`,
float `$ey`
): GmagickDraw
public function point(float `$x`, float `$y`): GmagickDraw
public function polygon(array `$coordinates`): GmagickDraw
public function polyline(array `$coordinate_array`): GmagickDraw
public function rectangle(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`
): GmagickDraw
public function rotate(float `$degrees`): GmagickDraw
public function roundrectangle(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$rx`,
float `$ry`
): GmagickDraw
public function scale(float `$x`, float `$y`): GmagickDraw
public function setfillcolor(mixed `$color`): GmagickDraw
public function setfillopacity(float `$fill_opacity`): GmagickDraw
public function setfont(string `$font`): GmagickDraw
public function setfontsize(float `$pointsize`): GmagickDraw
public function setfontstyle(int `$style`): GmagickDraw
public function setfontweight(int `$weight`): GmagickDraw
public function setstrokecolor(mixed `$color`): GmagickDraw
public function setstrokeopacity(float `$stroke_opacity`): GmagickDraw
public function setstrokewidth(float `$width`): GmagickDraw
public function settextdecoration(int `$decoration`): GmagickDraw
public function settextencoding(string `$encoding`): GmagickDraw
}

# GmagickDraw::annotate

(PECL gmagick >= Unknown)

GmagickDraw::annotate — 画像の上にテキストを描画する

### 説明

public function GmagickDraw::annotate(float `$x`, float `$y`, string `$text`): GmagickDraw

画像の上にテキストを描画します。

### パラメータ

`x`
  テキストの左端の x 座標。
`y`
  テキストのベースラインの y 座標。
`text`
  描画するテキスト。

### 戻り値

GmagickDraw オブジェクトを返します。

# GmagickDraw::arc

(PECL gmagick >= Unknown)

GmagickDraw::arc — 弧を描く

### 説明

public function 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::bezier

(PECL gmagick >= Unknown)

GmagickDraw::bezier — ベジエ曲線を描く

### 説明

public function GmagickDraw::bezier(array `$coordinate_array`): GmagickDraw

指定した点を通るベジエ曲線を画像上に描きます。

### パラメータ

`coordinate_array`
  座標の配列。

### 戻り値

GmagickDraw オブジェクトを返します。

# GmagickDraw::ellipse

(PECL gmagick >= Unknown)

GmagickDraw::ellipse — 楕円を画像上に描く

### 説明

public function 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::getfillcolor

(PECL gmagick >= Unknown)

GmagickDraw::getfillcolor — 塗りつぶし色を返す

### 説明

public function GmagickDraw::getfillcolor(): GmagickPixel

オブジェクトを塗りつぶすときに使う色を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

オブジェクトを塗りつぶすときに使う色の GmagickPixel を返します。

# GmagickDraw::getfillopacity

(PECL gmagick >= Unknown)

GmagickDraw::getfillopacity — 描画に使う不透明度を返す

### 説明

public function GmagickDraw::getfillopacity(): float

描画に使う不透明度を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

塗りつぶしの色やテクスチャに使う不透明度を返します。完全に不透明な状態が 1.0 になります。

# GmagickDraw::getfont

(PECL gmagick >= Unknown)

GmagickDraw::getfont — フォントを返す

### 説明

public function GmagickDraw::getfont(): mixed

テキストのアノテーションで使うフォントを表す文字列を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に文字列を返します。フォントが設定されていない場合は `false` を返します。

# GmagickDraw::getfontsize

(PECL gmagick >= Unknown)

GmagickDraw::getfontsize — フォントのポイント数を返す

### 説明

public function GmagickDraw::getfontsize(): float

テキストのアノテーションで使うフォントのポイント数を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

現在の GmagickDraw オブジェクトに関連づけられたフォントのサイズを返します。

# GmagickDraw::getfontstyle

(PECL gmagick >= Unknown)

GmagickDraw::getfontstyle — フォントスタイルを返す

### 説明

public function GmagickDraw::getfontstyle(): int

テキストのアノテーションで使うフォントのスタイルを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

GmagickDraw オブジェクトに関連づけられたフォントスタイル定数 (STYLE_) を返します。 スタイルが設定されていない場合は `0` を返します。

# GmagickDraw::getfontweight

(PECL gmagick >= Unknown)

GmagickDraw::getfontweight — フォントのウェイトを返す

### 説明

public function GmagickDraw::getfontweight(): int

テキストのアノテーションで使うフォントのウェイトを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に整数値を返します。ウェイトが設定されていない場合は 0 を返します。

# GmagickDraw::getstrokecolor

(PECL gmagick >= Unknown)

GmagickDraw::getstrokecolor — オブジェクトの輪郭の描画に使う色を返す

### 説明

public function GmagickDraw::getstrokecolor(): GmagickPixel

オブジェクトの輪郭の描画に使う色を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

色を表す GmagickPixel オブジェクトを返します。

# GmagickDraw::getstrokeopacity

(PECL gmagick >= Unknown)

GmagickDraw::getstrokeopacity — オブジェクトの輪郭の不透明度を返す

### 説明

public function GmagickDraw::getstrokeopacity(): float

オブジェクトの輪郭の不透明度を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

不透明度を表す float 型の数値を返します。

# GmagickDraw::getstrokewidth

(PECL gmagick >= Unknown)

GmagickDraw::getstrokewidth — オブジェクトの輪郭の描画に使う線の幅を返す

### 説明

public function GmagickDraw::getstrokewidth(): float

オブジェクトの輪郭の描画に使う線の幅を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

線の幅を表す float 型の値を返します。

# GmagickDraw::gettextdecoration

(PECL gmagick >= Unknown)

GmagickDraw::gettextdecoration — テキストのデコレーションを返す

### 説明

public function GmagickDraw::gettextdecoration(): int

テキストのアノテーションに適用するデコレーションを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

DECORATION_ 定数のいずれかを返します。デコレーションが設定されていない場合は 0 を返します。

# GmagickDraw::gettextencoding

(PECL gmagick >= Unknown)

GmagickDraw::gettextencoding — テキストのアノテーションで使うコードセットを返す

### 説明

public function GmagickDraw::gettextencoding(): mixed

テキストのアノテーションで使うコードセットを表す文字列を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

コードセットを表す文字列を返します。 エンコーディングが設定されていない場合は `false` を返します。

# GmagickDraw::line

(PECL gmagick >= Unknown)

GmagickDraw::line — 直線を描く

### 説明

public function GmagickDraw::line(
float `$sx`,
float `$sy`,
float `$ex`,
float `$ey`
): GmagickDraw

現在の描画色、不透明度、線幅を使って画像上に直線を描きます。

### パラメータ

`sx`
  開始位置の x 座標。
`sy`
  開始位置の y 座標。
`ex`
  終了位置の x 座標。
`ey`
  終了位置の y 座標。

### 戻り値

GmagickDraw オブジェクトを返します。

# GmagickDraw::point

(PECL gmagick >= Unknown)

GmagickDraw::point — 点を描く

### 説明

public function GmagickDraw::point(float `$x`, float `$y`): GmagickDraw

現在の描画色と太さを使って、指定した座標に点を描きます。

### パラメータ

`x`
  点の x 座標。
`y`
  点の y 座標。

### 戻り値

GmagickDraw オブジェクトを返します。

# GmagickDraw::polygon

(PECL gmagick >= Unknown)

GmagickDraw::polygon — 多角形を描く

### 説明

public function GmagickDraw::polygon(array `$coordinates`): GmagickDraw

現在の描画色、線幅、塗りつぶし色、塗りつぶしテクスチャを使って、指定した座標の配列による多角形を描きます。

### パラメータ

`coordinates`
  座標の配列。

### 戻り値

GmagickDraw オブジェクトを返します。

# GmagickDraw::polyline

(PECL gmagick >= Unknown)

GmagickDraw::polyline — ポリラインを描く

### 説明

public function GmagickDraw::polyline(array `$coordinate_array`): GmagickDraw

現在の描画色、線幅、塗りつぶし色、塗りつぶしテクスチャを使って、指定した座標の配列によるポリラインを描きます。

### パラメータ

`coordinate_array`
  座標の配列。

### 戻り値

GmagickDraw オブジェクトを返します。

# GmagickDraw::rectangle

(PECL gmagick >= Unknown)

GmagickDraw::rectangle — 矩形を描く

### 説明

public function GmagickDraw::rectangle(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`
): GmagickDraw

二つの座標を指定して、現在の描画色と線幅そして塗りつぶし設定を使った矩形を描きます。

### パラメータ

`x1`
  最初の x 座標。
`y1`
  最初の y 座標。
`x2`
  二番目の x 座標。
`y2`
  二番目の y 座標。

### 戻り値

GmagickDraw オブジェクトを返します。

# GmagickDraw::rotate

(PECL gmagick >= Unknown)

GmagickDraw::rotate — 指定した回転角を現在の座標空間に適用する

### 説明

public function GmagickDraw::rotate(float `$degrees`): GmagickDraw

指定した回転角を現在の座標空間に適用します。

### パラメータ

`degrees`
  回転角度。

### 戻り値

GmagickDraw オブジェクトを返します。

# GmagickDraw::roundrectangle

(PECL gmagick >= Unknown)

GmagickDraw::roundrectangle — 角が丸い矩形を描く

### 説明

public function 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::scale

(PECL gmagick >= Unknown)

GmagickDraw::scale — 倍率を調整する

### 説明

public function GmagickDraw::scale(float `$x`, float `$y`): GmagickDraw

現在の座標空間に対して水平方向と垂直方向の倍率を調整します。

### パラメータ

`x`
  水平方向の倍率。
`y`
  垂直方向の倍率。

### 戻り値

GmagickDraw オブジェクトを返します。

# GmagickDraw::setfillcolor

(PECL gmagick >= Unknown)

GmagickDraw::setfillcolor — オブジェクトの塗りつぶしに使う色を設定する

### 説明

public function GmagickDraw::setfillcolor(mixed `$color`): GmagickDraw

オブジェクトの塗りつぶしに使う色を設定します。

### パラメータ

`color`
  塗りつぶしに使う色を表す GmagickPixel オブジェクトあるいは文字列。

### 戻り値

成功した場合に GmagickDraw オブジェクトを返します。

# GmagickDraw::setfillopacity

(PECL gmagick >= Unknown)

GmagickDraw::setfillopacity — 不透明度を設定する

### 説明

public function GmagickDraw::setfillopacity(float `$fill_opacity`): GmagickDraw

塗りつぶし色や塗りつぶしテクスチャを使った描画のときに使う不透明度を設定します。 1.0 にすると、完全に不透明になります。

### パラメータ

`fill_opacity`
  塗りつぶしの不透明度。

### 戻り値

GmagickDraw オブジェクトを返します。

# GmagickDraw::setfont

(PECL gmagick >= Unknown)

GmagickDraw::setfont — テキストのアノテーションで使うフォントの完全な名前を設定する

### 説明

public function GmagickDraw::setfont(string `$font`): GmagickDraw

テキストのアノテーションで使うフォントの完全な名前を設定します。

### パラメータ

`font`
  フォント名。

### 戻り値

GmagickDraw オブジェクトを返します。

# GmagickDraw::setfontsize

(PECL gmagick >= Unknown)

GmagickDraw::setfontsize — テキストのアノテーションで使うフォントのポイント数を設定する

### 説明

public function GmagickDraw::setfontsize(float `$pointsize`): GmagickDraw

テキストのアノテーションで使うフォントのポイント数を設定します。

### パラメータ

`pointsize`
  テキストのポイント数。

### 戻り値

GmagickDraw オブジェクトを返します。

# GmagickDraw::setfontstyle

(PECL gmagick >= Unknown)

GmagickDraw::setfontstyle — テキストのアノテーションで使うフォントのスタイルを設定する

### 説明

public function GmagickDraw::setfontstyle(int `$style`): GmagickDraw

テキストのアノテーションで使うフォントのスタイルを設定します。 AnyStyle はワイルドカードで、「気にしない」という意味になります。

### パラメータ

`style`
  フォントスタイル (NormalStyle, ItalicStyle, ObliqueStyle, AnyStyle)。

### 戻り値

GmagickDraw オブジェクトを返します。

# GmagickDraw::setfontweight

(PECL gmagick >= Unknown)

GmagickDraw::setfontweight — フォントのウェイトを設定する

### 説明

public function GmagickDraw::setfontweight(int `$weight`): GmagickDraw

テキストのアノテーションで使うフォントのウェイトを設定します。

### パラメータ

`weight`
  フォントのウェイト (100-900 の範囲が有効)。

### 戻り値

GmagickDraw オブジェクトを返します。

# GmagickDraw::setstrokecolor

(PECL gmagick >= Unknown)

GmagickDraw::setstrokecolor — オブジェクトの輪郭の描画に使う色を設定する

### 説明

public function GmagickDraw::setstrokecolor(mixed `$color`): GmagickDraw

オブジェクトの輪郭の描画に使う色を設定します。

### パラメータ

`color`
  輪郭の色を表す GmagickPixel オブジェクトあるいは文字列。

### 戻り値

成功した場合に GmagickDraw オブジェクトを返します。

# GmagickDraw::setstrokeopacity

(PECL gmagick >= Unknown)

GmagickDraw::setstrokeopacity — オブジェクトの輪郭の不透明度を設定する

### 説明

public function GmagickDraw::setstrokeopacity(float `$stroke_opacity`): GmagickDraw

オブジェクトの輪郭の不透明度を設定します。

### パラメータ

`stroke_opacity`
  不透明度。1.0 が完全な不透明を表します。

### 戻り値

GmagickDraw オブジェクトを返します。

# GmagickDraw::setstrokewidth

(PECL gmagick >= Unknown)

GmagickDraw::setstrokewidth — オブジェクトの輪郭の描画に使う線の幅を設定する

### 説明

public function GmagickDraw::setstrokewidth(float `$width`): GmagickDraw

オブジェクトの輪郭の描画に使う線の幅を設定します。

### パラメータ

`width`
  線の幅。

### 戻り値

GmagickDraw オブジェクトを返します。

# GmagickDraw::settextdecoration

(PECL gmagick >= Unknown)

GmagickDraw::settextdecoration — デコレーションを設定する

### 説明

public function GmagickDraw::settextdecoration(int `$decoration`): GmagickDraw

テキストのアノテーションに適用するデコレーションを設定します。

### パラメータ

`int`
  テキストのデコレーション。NoDecoration、UnderlineDecoration、OverlineDecoration あるいは LineThroughDecoration のいずれか。

### 戻り値

GmagickDraw オブジェクトを返します。

# GmagickDraw::settextencoding

(PECL gmagick >= Unknown)

GmagickDraw::settextencoding — テキストのコードセットを設定する

### 説明

public function GmagickDraw::settextencoding(string `$encoding`): GmagickDraw

テキストのアノテーションで使うコードセットを表す文字列を設定します。 現時点で使える文字エンコーディングは "UTF-8" だけで、 これは Unicode をバイト列として使います。 空文字列を指定すると、テキストのエンコーディングをシステムのデフォルトに合わせます。 Unicode を使ったテキストのアノテーションをするには、Unicode に対応したフォントが必要です。

### パラメータ

`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 — テキストのコードセットを設定する

# GmagickPixel クラス

(PECL gmagick >= Unknown)

## はじめに

## クラス概要

class GmagickPixel {
/* メソッド */
public function __construct(string `$color` = ?)
public function getcolor(bool `$as_array` = `false`, bool `$normalize_array` = `false`): mixed
public function getcolorcount(): int
public function getcolorvalue(int `$color`): float
public function setcolor(string `$color`): GmagickPixel
public function setcolorvalue(int `$color`, float `$value`): GmagickPixel
}

# GmagickPixel::__construct

(PECL gmagick >= Unknown)

GmagickPixel::__construct — GmagickPixel のコンストラクタ

### 説明

public function GmagickPixel::__construct(string `$color` = ?)

GmagickPixel オブジェクトを作ります。 色を指定した場合は、オブジェクトを作ってからその色で初期化したものを返します。

### パラメータ

`color`
  オプションで指定する色文字列。このオブジェクトの初期値として使います。

# GmagickPixel::getcolor

(PECL gmagick >= Unknown)

GmagickPixel::getcolor — 色を返す

### 説明

public function GmagickPixel::getcolor(bool `$as_array` = `false`, bool `$normalize_array` = `false`): mixed

GmagickPixel オブジェクトの色を文字列あるいは配列で返します。 透明度が設定されているときは、リストの四番目の値として返します。

### パラメータ

`as_array`
  `true` にすると、戻り値を文字列ではなく配列にします。
`normalize_array`
  `true` にすると、色の値を正規化します。

### 戻り値

各チャネルの値を文字列あるいは配列で返します。`normalize_array` に `true` を市得治した場合は正規化をします。エラー時には GmagickPixelException をスローします。

# GmagickPixel::getcolorcount

(PECL gmagick >= Unknown)

GmagickPixel::getcolorcount — この色の色カウントを返す

### 説明

public function GmagickPixel::getcolorcount(): int

この色に関連づけられた色カウントを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に色カウントを整数値で返します。 失敗した場合は GmagickPixelException をスローします。

# GmagickPixel::getcolorvalue

(PECL gmagick >= Unknown)

GmagickPixel::getcolorvalue — 指定した色チャネルの正規化した値を取得する

### 説明

public function GmagickPixel::getcolorvalue(int `$color`): float

指定した色チャネルの値を取得します。0 から 1 までの間の浮動小数点数値になります。

### パラメータ

`color`
  調べたいチャネル。Gmagick チャネル定数で指定します。

### 戻り値

チャネルの値を、正規化した浮動小数点数値で返します。 エラー時には GmagickPixelException をスローします。

# GmagickPixel::setcolor

(PECL gmagick >= Unknown)

GmagickPixel::setcolor — 色を設定する

### 説明

public function GmagickPixel::setcolor(string `$color`): GmagickPixel

GmagickPixel オブジェクトの色を文字列で設定します ("blue"、"#0000ff"、"rgb(0,0,255)"、"cmyk(100,100,100,10)" など)。

### パラメータ

`color`
  GmagickPixel オブジェクトを初期化するときに使う色。

### 戻り値

GmagickPixel オブジェクトを返します。

# GmagickPixel::setcolorvalue

(PECL gmagick >= Unknown)

GmagickPixel::setcolorvalue — 色チャネルの正規化した値を設定する

### 説明

public function GmagickPixel::setcolorvalue(int `$color`, float `$value`): GmagickPixel

このオブジェクトの指定したチャネルの値を設定します。 これは 0 から 1 までの間の値になります。 この関数を使って GmagickPixel オブジェクトの透明度チャネルを設定できます。

### パラメータ

`color`
  Gmagick チャネル定数のいずれか。
`value`
  設定したい値。0 から 1 までの範囲で指定します。

### 戻り値

GmagickPixel オブジェクトを返します。

## 目次

- GmagickPixel::__construct — GmagickPixel のコンストラクタ
- GmagickPixel::getcolor — 色を返す
- GmagickPixel::getcolorcount — この色の色カウントを返す
- GmagickPixel::getcolorvalue — 指定した色チャネルの正規化した値を取得する
- GmagickPixel::setcolor — 色を設定する
- GmagickPixel::setcolorvalue — 色チャネルの正規化した値を設定する

- インストール/設定
  - 要件
  - インストール手順
- 定義済み定数
- 例
- 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 — 色チャネルの正規化した値を設定する

# 画像処理 (ImageMagick)

# はじめに

警告

この拡張モジュールは、 実験的 なものです。この拡張モジュールの動作・ 関数名・その他ドキュメントに書かれている事項は、予告なく、将来的な PHP のリリースにおいて変更される可能性があります。 このモジュールは自己責任で使用してください。

Imagick は、ImageMagick API を使用して画像の作成や修正を行う ネイティブ PHP 拡張モジュールです。

## ImageMagick について

ImageMagick は、ビットマップ画像の作成や修正を行うソフトウェア群です。 さまざまな (100 をこえる) 形式の画像の読み書きや変換に対応しており、 DPX や EXR、GIF、JPEG、JPEG-2000、PDF、PhotoCD、PNG、Postscript、SVG そして TIFF といった形式を扱うことができます。

ImageMagick Studio LLC は、 フリーソフトウェアによる画像処理ソリューションを提供することを目指す非営利組織です。

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定

## 要件

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

`COMPOSITE_*` 定数
`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 以降。

# 例

## 目次

- 基本的な使用法

## 基本的な使用法

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 クラス

(PECL imagick 2, PECL imagick 3)

## クラス概要

class Imagick implements Iterator {
public function __construct(mixed `$files` = ?)
public function adaptiveBlurImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function adaptiveResizeImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool
public function adaptiveSharpenImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function adaptiveThresholdImage(int `$width`, int `$height`, int `$offset`): bool
public function addImage(Imagick `$source`): bool
public function addNoiseImage(int `$noise_type`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function affineTransformImage(ImagickDraw `$matrix`): bool
public function animateImages(string `$x_server`): bool
public function annotateImage(
ImagickDraw `$draw_settings`,
float `$x`,
float `$y`,
float `$angle`,
string `$text`
): bool
public function appendImages(bool `$stack`): Imagick
public function autoLevelImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function averageImages(): Imagick
public function blackThresholdImage(mixed `$threshold`): bool
public function blueShiftImage(float `$factor` = 1.5): bool
public function blurImage(float `$radius`, float `$sigma`, int `$channel` = ?): bool
public function borderImage(mixed `$bordercolor`, int `$width`, int `$height`): bool
public function brightnessContrastImage(float `$brightness`, float `$contrast`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function charcoalImage(float `$radius`, float `$sigma`): bool
public function chopImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function clampImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function clear(): bool
public function clipImage(): bool
public function clipImagePath(string `$pathname`, string `$inside`): void
public function clipPathImage(string `$pathname`, bool `$inside`): bool
public function clone(): Imagick
public function clutImage(Imagick `$lookup_table`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function coalesceImages(): Imagick
public function colorFloodfillImage(
mixed `$fill`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`
): bool
public function colorizeImage(mixed `$colorize`, mixed `$opacity`, bool `$legacy` = `false`): bool
public function colorMatrixImage(array `$color_matrix`): bool
public function combineImages(int `$channelType`): Imagick
public function commentImage(string `$comment`): bool
public function compareImageChannels(Imagick `$image`, int `$channelType`, int `$metricType`): array
public function compareImageLayers(int `$method`): Imagick
public function compareImages(Imagick `$compare`, int `$metric`): array
public function compositeImage(
Imagick `$composite_object`,
int `$composite`,
int `$x`,
int `$y`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function contrastImage(bool `$sharpen`): bool
public function contrastStretchImage(float `$black_point`, float `$white_point`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function convolveImage(array `$kernel`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function count(int `$mode` = 0): int
public function cropImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function cropThumbnailImage(int `$width`, int `$height`, bool `$legacy` = `false`): bool
public function current(): Imagick
public function cycleColormapImage(int `$displace`): bool
public function decipherImage(string `$passphrase`): bool
public function deconstructImages(): Imagick
public function deleteImageArtifact(string `$artifact`): bool
public function deleteImageProperty(string `$name`): bool
public function deskewImage(float `$threshold`): bool
public function despeckleImage(): bool
public function destroy(): bool
public function displayImage(string `$servername`): bool
public function displayImages(string `$servername`): bool
public function distortImage(int `$method`, array `$arguments`, bool `$bestfit`): bool
public function drawImage(ImagickDraw `$draw`): bool
public function edgeImage(float `$radius`): bool
public function embossImage(float `$radius`, float `$sigma`): bool
public function encipherImage(string `$passphrase`): bool
public function enhanceImage(): bool
public function equalizeImage(): bool
public function evaluateImage(int `$op`, float `$constant`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function exportImagePixels(
int `$x`,
int `$y`,
int `$width`,
int `$height`,
string `$map`,
int `$STORAGE`
): array
public function extentImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function filter(ImagickKernel `$ImagickKernel`, int `$channel` = Imagick::CHANNEL_UNDEFINED): bool
public function flattenImages(): Imagick
public function flipImage(): bool
public function floodFillPaintImage(
mixed `$fill`,
float `$fuzz`,
mixed `$target`,
int `$x`,
int `$y`,
bool `$invert`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function flopImage(): bool
public function forwardFourierTransformimage(bool `$magnitude`): bool
public function frameImage(
mixed `$matte_color`,
int `$width`,
int `$height`,
int `$inner_bevel`,
int `$outer_bevel`
): bool
public function functionImage(int `$function`, array `$arguments`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function fxImage(string `$expression`, int `$channel` = Imagick::CHANNEL_DEFAULT): Imagick
public function gammaImage(float `$gamma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function gaussianBlurImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function getColorspace(): int
public function getCompression(): int
public function getCompressionQuality(): int
public static function getCopyright(): string
public function getFilename(): string
public function getFont(): string
public function getFormat(): string
public function getGravity(): int
public static function getHomeURL(): string
public function getImage(): Imagick
public function getImageAlphaChannel(): bool
public function getImageArtifact(string `$artifact`): string
public function getImageAttribute(string `$key`): string
public function getImageBackgroundColor(): ImagickPixel
public function getImageBlob(): string
public function getImageBluePrimary(): array
public function getImageBorderColor(): ImagickPixel
public function getImageChannelDepth(int `$channel`): int
public function getImageChannelDistortion(Imagick `$reference`, int `$channel`, int `$metric`): float
public function getImageChannelDistortions(Imagick `$reference`, int `$metric`, int `$channel` = Imagick::CHANNEL_DEFAULT): float
public function getImageChannelExtrema(int `$channel`): array
public function getImageChannelKurtosis(int `$channel` = Imagick::CHANNEL_DEFAULT): array
public function getImageChannelMean(int `$channel`): array
public function getImageChannelRange(int `$channel`): array
public function getImageChannelStatistics(): array
public function getImageClipMask(): Imagick
public function getImageColormapColor(int `$index`): ImagickPixel
public function getImageColors(): int
public function getImageColorspace(): int
public function getImageCompose(): int
public function getImageCompression(): int
public function getImageCompressionQuality(): int
public function getImageDelay(): int
public function getImageDepth(): int
public function getImageDispose(): int
public function getImageDistortion(MagickWand `$reference`, int `$metric`): float
public function getImageExtrema(): array
public function getImageFilename(): string
public function getImageFormat(): string
public function getImageGamma(): float
public function getImageGeometry(): array
public function getImageGravity(): int
public function getImageGreenPrimary(): array
public function getImageHeight(): int
public function getImageHistogram(): array
public function getImageIndex(): int
public function getImageInterlaceScheme(): int
public function getImageInterpolateMethod(): int
public function getImageIterations(): int
public function getImageLength(): int
public function getImageMatte(): bool
public function getImageMatteColor(): ImagickPixel
public function getImageMimeType(): string
public function getImageOrientation(): int
public function getImagePage(): array
public function getImagePixelColor(int `$x`, int `$y`): ImagickPixel
public function getImageProfile(string `$name`): string
public function getImageProfiles(string `$pattern` = "*", bool `$include_values` = `true`): array
public function getImageProperties(string `$pattern` = "*", bool `$include_values` = `true`): array
public function getImageProperty(string `$name`): string
public function getImageRedPrimary(): array
public function getImageRegion(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): Imagick
public function getImageRenderingIntent(): int
public function getImageResolution(): array
public function getImagesBlob(): string
public function getImageScene(): int
public function getImageSignature(): string
public function getImageSize(): int
public function getImageTicksPerSecond(): int
public function getImageTotalInkDensity(): float
public function getImageType(): int
public function getImageUnits(): int
public function getImageVirtualPixelMethod(): int
public function getImageWhitePoint(): array
public function getImageWidth(): int
public function getInterlaceScheme(): int
public function getIteratorIndex(): int
public function getNumberImages(): int
public function getOption(string `$key`): string
public static function getPackageName(): string
public function getPage(): array
public function getPixelIterator(): ImagickPixelIterator
public function getPixelRegionIterator(
int `$x`,
int `$y`,
int `$columns`,
int `$rows`
): ImagickPixelIterator
public function getPointSize(): float
public static function getQuantum(): int
public static function getQuantumDepth(): array
public static function getQuantumRange(): array
public static function getRegistry(string `$key`): string
public static function getReleaseDate(): string
public static function getResource(int `$type`): int
public static function getResourceLimit(int `$type`): int
public function getSamplingFactors(): array
public function getSize(): array
public function getSizeOffset(): int
public static function getVersion(): array
public function haldClutImage(Imagick `$clut`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function hasNextImage(): bool
public function hasPreviousImage(): bool
public function identifyFormat(string `$embedText`): string|false
public function identifyImage(bool `$appendRawOutput` = `false`): array
public function implodeImage(float `$radius`): bool
public function importImagePixels(
int `$x`,
int `$y`,
int `$width`,
int `$height`,
string `$map`,
int `$storage`,
array `$pixels`
): bool
public function inverseFourierTransformImage(Imagick `$complement`, bool `$magnitude`): bool
public function labelImage(string `$label`): bool
public function levelImage(
float `$blackPoint`,
float `$gamma`,
float `$whitePoint`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function linearStretchImage(float `$blackPoint`, float `$whitePoint`): bool
public function liquidRescaleImage(
int `$width`,
int `$height`,
float `$delta_x`,
float `$rigidity`
): bool
public static function listRegistry(): array
public function magnifyImage(): bool
public function mapImage(Imagick `$map`, bool `$dither`): bool
public function matteFloodfillImage(
float `$alpha`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`
): bool
public function medianFilterImage(float `$radius`): bool
public function mergeImageLayers(int `$layer_method`): Imagick
public function minifyImage(): bool
public function modulateImage(float `$brightness`, float `$saturation`, float `$hue`): bool
public function montageImage(
ImagickDraw `$draw`,
string `$tile_geometry`,
string `$thumbnail_geometry`,
int `$mode`,
string `$frame`
): Imagick
public function morphImages(int `$number_frames`): Imagick
public function morphology(
int `$morphologyMethod`,
int `$iterations`,
ImagickKernel `$ImagickKernel`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function mosaicImages(): Imagick
public function motionBlurImage(
float `$radius`,
float `$sigma`,
float `$angle`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function negateImage(bool `$gray`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function newImage(
int `$cols`,
int `$rows`,
mixed `$background`,
string `$format` = ?
): bool
public function newPseudoImage(int `$columns`, int `$rows`, string `$pseudoString`): bool
public function nextImage(): bool
public function normalizeImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function oilPaintImage(float `$radius`): bool
public function opaquePaintImage(
mixed `$target`,
mixed `$fill`,
float `$fuzz`,
bool `$invert`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function optimizeImageLayers(): bool
public function orderedPosterizeImage(string `$threshold_map`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function paintFloodfillImage(
mixed `$fill`,
float `$fuzz`,
mixed `$bordercolor`,
int `$x`,
int `$y`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function paintOpaqueImage(
mixed `$target`,
mixed `$fill`,
float `$fuzz`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function paintTransparentImage(mixed `$target`, float `$alpha`, float `$fuzz`): bool
public function pingImage(string `$filename`): bool
public function pingImageBlob(string `$image`): bool
public function pingImageFile(resource `$filehandle`, string `$fileName` = ?): bool
public function polaroidImage(ImagickDraw `$properties`, float `$angle`): bool
public function posterizeImage(int `$levels`, bool `$dither`): bool
public function previewImages(int `$preview`): bool
public function previousImage(): bool
public function profileImage(string `$name`, string `$profile` = ?): bool
public function quantizeImage(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool
public function quantizeImages(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool
public function queryFontMetrics(ImagickDraw `$properties`, string `$text`, bool `$multiline` = ?): array
public static function queryFonts(string `$pattern` = "*"): array
public static function queryFormats(string `$pattern` = "*"): array
public function radialBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function raiseImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`,
bool `$raise`
): bool
public function randomThresholdImage(float `$low`, float `$high`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function readImage(string `$filename`): bool
public function readImageBlob(string `$image`, string `$filename` = ?): bool
public function readImageFile(resource `$filehandle`, string `$fileName` = `null`): bool
public function readImages(array `$filenames`): bool
public function recolorImage(array `$matrix`): bool
public function reduceNoiseImage(float `$radius`): bool
public function remapImage(Imagick `$replacement`, int `$DITHER`): bool
public function removeImage(): bool
public function removeImageProfile(string `$name`): string
public function render(): bool
public function resampleImage(
float `$x_resolution`,
float `$y_resolution`,
int `$filter`,
float `$blur`
): bool
public function resetImagePage(string `$page`): bool
public function resizeImage(
int `$columns`,
int `$rows`,
int `$filter`,
float `$blur`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool
public function rollImage(int `$x`, int `$y`): bool
public function rotateImage(mixed `$background`, float `$degrees`): bool
public function rotationalBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function roundCorners(
float `$x_rounding`,
float `$y_rounding`,
float `$stroke_width` = 10,
float `$displace` = 5,
float `$size_correction` = -6
): bool
public function sampleImage(int `$columns`, int `$rows`): bool
public function scaleImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$legacy` = `false`
): bool
public function segmentImage(
int `$COLORSPACE`,
float `$cluster_threshold`,
float `$smooth_threshold`,
bool `$verbose` = `false`
): bool
public function selectiveBlurImage(
float `$radius`,
float `$sigma`,
float `$threshold`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function separateImageChannel(int `$channel`): bool
public function sepiaToneImage(float `$threshold`): bool
public function setBackgroundColor(mixed `$background`): bool
public function setColorspace(int `$COLORSPACE`): bool
public function setCompression(int `$compression`): bool
public function setCompressionQuality(int `$quality`): bool
public function setFilename(string `$filename`): bool
public function setFirstIterator(): bool
public function setFont(string `$font`): bool
public function setFormat(string `$format`): bool
public function setGravity(int `$gravity`): bool
public function setImage(Imagick `$replace`): bool
public function setImageAlphaChannel(int `$mode`): bool
public function setImageArtifact(string `$artifact`, string `$value`): bool
public function setImageAttribute(string `$key`, string `$value`): bool
public function setImageBackgroundColor(mixed `$background`): bool
public function setImageBias(float `$bias`): bool
public function setImageBiasQuantum(float `$bias`): void
public function setImageBluePrimary(float `$x`, float `$y`): bool
public function setImageBorderColor(mixed `$border`): bool
public function setImageChannelDepth(int `$channel`, int `$depth`): bool
public function setImageClipMask(Imagick `$clip_mask`): bool
public function setImageColormapColor(int `$index`, ImagickPixel `$color`): bool
public function setImageColorspace(int `$colorspace`): bool
public function setImageCompose(int `$compose`): bool
public function setImageCompression(int `$compression`): bool
public function setImageCompressionQuality(int `$quality`): bool
public function setImageDelay(int `$delay`): bool
public function setImageDepth(int `$depth`): bool
public function setImageDispose(int `$dispose`): bool
public function setImageExtent(int `$columns`, int `$rows`): bool
public function setImageFilename(string `$filename`): bool
public function setImageFormat(string `$format`): bool
public function setImageGamma(float `$gamma`): bool
public function setImageGravity(int `$gravity`): bool
public function setImageGreenPrimary(float `$x`, float `$y`): bool
public function setImageIndex(int `$index`): bool
public function setImageInterlaceScheme(int `$interlace_scheme`): bool
public function setImageInterpolateMethod(int `$method`): bool
public function setImageIterations(int `$iterations`): bool
public function setImageMatte(bool `$matte`): bool
public function setImageMatteColor(mixed `$matte`): bool
public function setImageOpacity(float `$opacity`): bool
public function setImageOrientation(int `$orientation`): bool
public function setImagePage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function setImageProfile(string `$name`, string `$profile`): bool
public function setImageProperty(string `$name`, string `$value`): bool
public function setImageRedPrimary(float `$x`, float `$y`): bool
public function setImageRenderingIntent(int `$rendering_intent`): bool
public function setImageResolution(float `$x_resolution`, float `$y_resolution`): bool
public function setImageScene(int `$scene`): bool
public function setImageTicksPerSecond(int `$ticks_per_second`): bool
public function setImageType(int `$image_type`): bool
public function setImageUnits(int `$units`): bool
public function setImageVirtualPixelMethod(int `$method`): bool
public function setImageWhitePoint(float `$x`, float `$y`): bool
public function setInterlaceScheme(int `$interlace_scheme`): bool
public function setIteratorIndex(int `$index`): bool
public function setLastIterator(): bool
public function setOption(string `$key`, string `$value`): bool
public function setPage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function setPointSize(float `$point_size`): bool
public function setProgressMonitor(callable `$callback`): bool
public static function setRegistry(string `$key`, string `$value`): bool
public function setResolution(float `$x_resolution`, float `$y_resolution`): bool
public static function setResourceLimit(int `$type`, int `$limit`): bool
public function setSamplingFactors(array `$factors`): bool
public function setSize(int `$columns`, int `$rows`): bool
public function setSizeOffset(int `$columns`, int `$rows`, int `$offset`): bool
public function setType(int `$image_type`): bool
public function shadeImage(bool `$gray`, float `$azimuth`, float `$elevation`): bool
public function shadowImage(
float `$opacity`,
float `$sigma`,
int `$x`,
int `$y`
): bool
public function sharpenImage(float `$radius`, float `$sigma`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function shaveImage(int `$columns`, int `$rows`): bool
public function shearImage(mixed `$background`, float `$x_shear`, float `$y_shear`): bool
public function sigmoidalContrastImage(
bool `$sharpen`,
float `$alpha`,
float `$beta`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function sketchImage(float `$radius`, float `$sigma`, float `$angle`): bool
public function smushImages(bool `$stack`, int `$offset`): Imagick
public function solarizeImage(int `$threshold`): bool
public function sparseColorImage(int `$SPARSE_METHOD`, array `$arguments`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function spliceImage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool
public function spreadImage(float `$radius`): bool
public function statisticImage(
int `$type`,
int `$width`,
int `$height`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function steganoImage(Imagick `$watermark_wand`, int `$offset`): Imagick
public function stereoImage(Imagick `$offset_wand`): bool
public function stripImage(): bool
public function subImageMatch(Imagick `$Imagick`, array `&$offset` = ?, float `&$similarity` = ?): Imagick
function swirlImage(float `$degrees`): bool
function textureImage(Imagick `$texture_wand`): Imagick
public function thresholdImage(float `$threshold`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool
public function thumbnailImage(
int `$columns`,
int `$rows`,
bool `$bestfit` = `false`,
bool `$fill` = `false`,
bool `$legacy` = `false`
): bool
public function tintImage(mixed `$tint`, mixed `$opacity`, bool `$legacy` = `false`): bool
public function __toString(): string
public function transformImage(string `$crop`, string `$geometry`): Imagick
public function transformImageColorspace(int `$colorspace`): bool
public function transparentPaintImage(
mixed `$target`,
float `$alpha`,
float `$fuzz`,
bool `$invert`
): bool
public function transposeImage(): bool
public function transverseImage(): bool
public function trimImage(float `$fuzz`): bool
public function uniqueImageColors(): bool
public function unsharpMaskImage(
float `$radius`,
float `$sigma`,
float `$amount`,
float `$threshold`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool
public function valid(): bool
public function vignetteImage(
float `$blackPoint`,
float `$whitePoint`,
int `$x`,
int `$y`
): bool
public function waveImage(float `$amplitude`, float `$length`): bool
public function whiteThresholdImage(mixed `$threshold`): bool
public function writeImage(string `$filename` = NULL): bool
public function writeImageFile(resource `$filehandle`, string `$format` = ?): bool
public function writeImages(string `$filename`, bool `$adjoin`): bool
public function 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

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveBlurImage — adaptive blur (順応性にじみ) フィルタを画像に追加する

### 説明

public function 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::blurImage() - blur (にじみ) フィルタを画像に追加する
- Imagick::motionBlurImage() - モーションブラーをシミュレートする
- Imagick::radialBlurImage() - 画像にラジアルブラーを施す

# Imagick::adaptiveResizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveResizeImage — データに依存する三角測量にもとづいて画像のサイズを変更する

### 説明

public function 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::adaptiveSharpenImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveSharpenImage — 順応して画像をシャープにする

### 説明

public function 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::adaptiveThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::adaptiveThresholdImage — 輝度の範囲にもとづいて各ピクセルの閾値を選択する

### 説明

public function 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::addImage

(PECL imagick 2, PECL imagick 3)

Imagick::addImage — 新しい画像を Imagick オブジェクトの画像リストに追加する

### 説明

public function Imagick::addImage(Imagick `$source`): bool

元オブジェクトの現在の位置にある新しい画像を、 Imagick オブジェクトの画像リストに追加します。 この操作を行うと、イテレータがリストの最後尾に移動します。

### パラメータ

`source`

  元の Imagick オブジェクト。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::addNoiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::addNoiseImage — ランダムなノイズを画像に追加する

### 説明

public function 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::affineTransformImage

(PECL imagick 2, PECL imagick 3)

Imagick::affineTransformImage — 画像を変換する

### 説明

public function 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::animateImages

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::animateImages — 画像を動かす

### 説明

public function Imagick::animateImages(string `$x_server`): bool

このメソッドは、ローカルあるいはリモートの X サーバーで画像を動かします。 このメソッドは Windows では使えません。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

`x_server`

  X サーバーのアドレス。

### 戻り値

成功した場合に `true` を返します。

### 参考

- Imagick::displayImage() - 画像を表示する

# Imagick::annotateImage

(PECL imagick 2, PECL imagick 3)

Imagick::annotateImage — 画像にテキストによる注記を加える

### 説明

public function 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::appendImages

(PECL imagick 2, PECL imagick 3)

Imagick::appendImages — 画像群を追加する

### 説明

public function 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::autoLevelImage

(PECL imagick 3 >= 3.3.0)

Imagick::autoLevelImage — 特定の画像チャネルのレベルを調整する

### 説明

public function Imagick::autoLevelImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool

最小値と最大値をフル quantum range にスケーリングすることで、特定の画像チャネルのレベルを調整します。

### パラメータ

`channel`

  自動レベル調整を適用するチャネル。

### 戻り値

成功した場合に `true` を返します。

### 例

例1 Imagick::autoLevelImage()

    <?php
    function autoLevelImage($imagePath) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->autoLevelImage();
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }

    ?>

# Imagick::averageImages

(PECL imagick 2, PECL imagick 3)

Imagick::averageImages — 画像群を平均化する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function Imagick::averageImages(): Imagick

画像群を平均化します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に Imagick インスタンスを返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::blackThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::blackThresholdImage — 閾値に満たないすべてのピクセルを黒にする

### 説明

public function 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();
    }

    ?>

# Imagick::blueShiftImage

(PECL imagick 3 >= 3.3.0)

Imagick::blueShiftImage — 画像の色を落ち着かせる

### 説明

public function Imagick::blueShiftImage(float `$factor` = 1.5): bool

月明かりに照らされた夜景をシミュレートするように、画像の色を落ち着かせます。

### パラメータ

`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();
    }

    ?>

# Imagick::blurImage

(PECL imagick 2, PECL imagick 3)

Imagick::blurImage — blur (にじみ) フィルタを画像に追加する

### 説明

public function 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::borderImage

(PECL imagick 2, PECL imagick 3)

Imagick::borderImage — 画像の周りを枠線で囲む

### 説明

public function 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();
    }

    ?>

# Imagick::brightnessContrastImage

(PECL imagick 3 >= 3.3.0)

Imagick::brightnessContrastImage — 画像の明るさやコントラストを変更する

### 説明

public function Imagick::brightnessContrastImage(float `$brightness`, float `$contrast`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

画像の明るさやコントラストを変更します。明るさとコントラストのパラメータを傾きと切片に変換し、多項式関数を呼び出して画像に適用します。

### パラメータ

`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::charcoalImage

(PECL imagick 2, PECL imagick 3)

Imagick::charcoalImage — 木炭画をシミュレートする

### 説明

public function 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::chopImage

(PECL imagick 2, PECL imagick 3)

Imagick::chopImage — 画像の一部を取り除き、切り詰める

### 説明

public function 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() - 画像の一部を抽出する

# Imagick::clampImage

(PECL imagick 3 >= 3.3.0)

Imagick::clampImage — 色の範囲を 0 から quantum depth までに制限する

### 説明

public function Imagick::clampImage(int `$channel` = Imagick::CHANNEL_DEFAULT): bool

色の範囲を 0 から quantum depth までに制限します。

### パラメータ

`channel`

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

# Imagick::clear

(PECL imagick 2, PECL imagick 3)

Imagick::clear — Imagick オブジェクトに関連付けられたすべてのリソースをクリアする

### 説明

public function Imagick::clear(): bool

Imagick オブジェクトに関連付けられたすべてのリソースをクリアします。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を返します。

# Imagick::clipImage

(PECL imagick 2, PECL imagick 3)

Imagick::clipImage — 8BIM プロファイルの最初のパスにそって切り取る

### 説明

public function Imagick::clipImage(): bool

8BIM プロファイルの最初のパスが存在する場合に、それにそって切り取ります。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::clipImagePath

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::clipImagePath — 8BIM プロファイルの名前付きパスがあればそれに沿ってクリップする

### 説明

public function Imagick::clipImagePath(string `$pathname`, string `$inside`): void

8BIM プロファイル内の名前付きパスが存在する場合、そのパスに沿ってクリップします。 以降の操作はパスの内側に対して適用されます。 Id の先頭に # を付けると番号付きパスを指定でき、 たとえば "#1" で最初のパスを使用します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`pathname`

`inside`

### 戻り値

# Imagick::clipPathImage

(PECL imagick 2, PECL imagick 3)

Imagick::clipPathImage — 8BIM プロファイルの指定した名前のパスにそって切り取る

### 説明

public function Imagick::clipPathImage(string `$pathname`, bool `$inside`): bool

8BIM プロファイルの指定した名前のパスが存在する場合に、それにそって切り取ります。 その後の操作はパスの内部に対してのみ有効となります。 番号で指定する場合は、番号の前に # を付加します。つまり "#1" とすると最初のパスを使用します。

### パラメータ

`pathname`

  パスの名前。

`inside`

  true の場合は、その後の操作はクリップパスの内側に対して適用されます。 それ以外の場合は、その後の操作はクリップパスの外側に対して適用されます。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::clone

(PECL imagick 2, PECL imagick 3)

Imagick::clone — Imagick オブジェクトの完全なコピーを作成する

### 説明

public function 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::clutImage

(PECL imagick 2, PECL imagick 3)

Imagick::clutImage — 画像の色を置き換える

### 説明

public function 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::coalesceImages

(PECL imagick 2, PECL imagick 3)

Imagick::coalesceImages — 複数の画像を合成する

### 説明

public function Imagick::coalesceImages(): Imagick

ページオフセットや処理方法を指定して、複数の画像を合成します。 典型的な使用例としては、たとえば GIF や MIFF、MNG といった画像シーケンスを最初に背景として指定し、 それ以降にさまざまなサイズやオフセットの画像を合成するというものがあります。 戻り値は、新規 Imagick オブジェクトとなります。 シーケンスの各画像のサイズは、最初の画像のサイズと同じになります。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に新規 Imagick オブジェクトを返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::colorFloodfillImage

(PECL imagick 2, PECL imagick 3)

Imagick::colorFloodfillImage — 対象にマッチする任意の点の色の値を変更する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function 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::colorizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::colorizeImage — 塗りつぶし色と画像を混合する

### 説明

public function 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();
    }

    ?>

# Imagick::colorMatrixImage

(PECL imagick 3 >= 3.3.0)

Imagick::colorMatrixImage — 画像に色変換を適用する

### 説明

public function Imagick::colorMatrixImage(array `$color_matrix`): bool

画像に色変換を適用します。 このメソッドは、彩度の変更、色相の回転、輝度からアルファへの変換、 その他さまざまな効果を実現できます。 可変サイズの変換行列を使うこともできますが、 通常は RGBA 画像には 5x5 の行列を、CMYKA（またはオフセット付きの RGBA） には 6x6 の行列を使います。 この行列は Adobe Flash で使われるものと似ていますが、 オフセットが 5 列目ではなく 6 列目にあり（CMYKA 画像をサポートするため）、 オフセットは正規化されています（Flash のオフセットを 255 で除算します）。

### パラメータ

`color_matrix`

### 戻り値

成功した場合に `true` を返します。

### 例

例1 Imagick::colorMatrixImage()

    <?php
    function colorMatrixImage($imagePath, $colorMatrix) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->setImageOpacity(1);

        //色変換行列は以下のようになります:
        //    $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::combineImages

(PECL imagick 2, PECL imagick 3)

Imagick::combineImages — ひとつあるいは複数の画像をひとつにまとめる

### 説明

public function Imagick::combineImages(int `$channelType`): Imagick

ひとつあるいは複数の画像をひとつにまとめます。 一連の画像の各ピクセルのグレースケール値が、 合成した画像の特定のチャネルの値となります。典型的なパターンでは 画像 1 => Red、画像 2 => Green、画像 3 => Blue などとなります。

### パラメータ

`channelType`

  そのチャネルモードで使用可能なチャネル定数のいずれか。 複数のチャネルを適用するには、channeltype 定数をビット演算子でまとめます。 チャネル定数 の一覧を参照ください。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::commentImage

(PECL imagick 2, PECL imagick 3)

Imagick::commentImage — コメントを画像に追加する

### 説明

public function 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::compareImageChannels

(PECL imagick 2, PECL imagick 3)

Imagick::compareImageChannels — ひとつあるいは複数の画像の差を返す

### 説明

public function Imagick::compareImageChannels(Imagick `$image`, int `$channelType`, int `$metricType`): array

ひとつあるいは複数の画像を比較し、差分の画像を返します。

### パラメータ

`image`

  比較する画像を含む Imagick オブジェクト。

`channelType`

  そのチャネルモードで使用可能なチャネル定数を指定します。 複数のチャネルを指定するには、チャネル型定数をビット演算子で結合します。 チャネル定数 の一覧を参照ください。

`metricType`

  メトリック型定数 のいずれか。

### 戻り値

`new_wand` と `distortion` を含む配列を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::compareImageLayers

(PECL imagick 2, PECL imagick 3)

Imagick::compareImageLayers — 複数の画像の中で最大の境界範囲を返す

### 説明

public function 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::compareImages

(PECL imagick 2, PECL imagick 3)

Imagick::compareImages — ある画像を再構築された画像と比較する

### 説明

public function 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::compositeImage

(PECL imagick 2, PECL imagick 3)

Imagick::compositeImage — ある画像を別の画像に合成する

### 説明

public function 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::__construct

(PECL imagick 2, PECL imagick 3)

Imagick::__construct — Imagick のコンストラクタ

### 説明

public function Imagick::__construct(mixed `$files` = ?)

指定した画像あるいは画像群用に Imagick のインスタンスを作ります。

### パラメータ

`files`

  読み込みたい画像へのパス、あるいは複数のパスの配列。 パスのファイル名にはワイルドカードを含めることができ、 また URL を指定することもできます。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::contrastImage

(PECL imagick 2, PECL imagick 3)

Imagick::contrastImage — 画像のコントラストを変更する

### 説明

public function 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::contrastStretchImage

(PECL imagick 2, PECL imagick 3)

Imagick::contrastStretchImage — カラー画像のコントラストを強調する

### 説明

public function 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::convolveImage

(PECL imagick 2, PECL imagick 3)

Imagick::convolveImage — 独自の畳み込み関数を画像に適用する

### 説明

public function 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();
    }

    ?>

# Imagick::count

(PECL imagick 3 >= 3.3.0)

Imagick::count — 画像の数を取得する

### 説明

public function Imagick::count(int `$mode` = 0): int

画像の数を返します。

### パラメータ

`mode`

  未使用の引数。現在、PHP には、countable オブジェクトに対して count() を呼び出す際に、このメソッドがパラメータを受け取る必要がある (場合もない) という、あまり明確に定義されていない機能があります。このパラメータは countable インターフェイスに準拠するために存在しますが、パラメータ自体は使用されません。

### 戻り値

画像の数を返します。

# Imagick::cropImage

(PECL imagick 2, PECL imagick 3)

Imagick::cropImage — 画像の一部を抽出する

### 説明

public function 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::cropThumbnailImage

(PECL imagick 2, PECL imagick 3)

Imagick::cropThumbnailImage — 切り取ってサムネイルを作成する

### 説明

public function Imagick::cropThumbnailImage(int `$width`, int `$height`, bool `$legacy` = `false`): bool

固定サイズのサムネイルを作成します。 まず画像のサイズを拡大あるいは縮小し、指定した範囲を中心から切り取ります。

### パラメータ

`width`

  サムネイルの幅。

`height`

  サムネイルの高さ。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::current

(PECL imagick 2, PECL imagick 3)

Imagick::current — 現在の Imagick オブジェクトへの参照を返す

### 説明

public function Imagick::current(): Imagick

現在の imagick オブジェクトへの参照を返し、 画像ポインタを正しいシーケンスに設定します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に自分自身を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::cycleColormapImage

(PECL imagick 2, PECL imagick 3)

Imagick::cycleColormapImage — 画像のカラーマップを移動する

### 説明

public function Imagick::cycleColormapImage(int `$displace`): bool

位置番号を指定して、画像のカラーマップを移動します。 カラーマップを何度か回転させると、サイケデリックな効果が得られます。

### パラメータ

`displace`

  カラーマップを移動させる量。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::decipherImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::decipherImage — 画像を復号する

### 説明

public function Imagick::decipherImage(string `$passphrase`): bool

暗号化された画像を復号します。画像の暗号化は Imagick::encipherImage() で行わなければなりません。 このメソッドは、ImageMagick バージョン 6.3.9 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

`passphrase`

  パスフレーズ。

### 戻り値

成功した場合に `true` を返します。

### 参考

- Imagick::encipherImage() - 画像を暗号化する

# Imagick::deconstructImages

(PECL imagick 2, PECL imagick 3)

Imagick::deconstructImages — 画像間の特定のピクセルの差を返す

### 説明

public function Imagick::deconstructImages(): Imagick

各画像をシーケンス内の次の画像と比較し、 最大の境界範囲を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に新しい Imagick オブジェクトを返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::deleteImageArtifact

(PECL imagick 3)

Imagick::deleteImageArtifact — 画像のアーチファクトを削除する

### 説明

public function Imagick::deleteImageArtifact(string `$artifact`): bool

画像に関連づけられたアーチファクトを削除します。プロパティとアーチファクトの違いは、 プロパティは public であるのに対してアーチファクトは private であるという点です。 このメソッドは、ImageMagick バージョン 6.5.7 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

`artifact`

  削除したいアーチファクトの名前。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

### 参考

- Imagick::setImageArtifact() - 画像のアーチファクトを設定する
- Imagick::getImageArtifact() - 画像のアーチファクトを取得する

# Imagick::deleteImageProperty

(PECL imagick 3 >= 3.3.0)

Imagick::deleteImageProperty — 画像のプロパティを削除する

### 説明

public function Imagick::deleteImageProperty(string `$name`): bool

画像のプロパティを削除します。

### パラメータ

`name`

  削除するプロパティの名前。

### 戻り値

成功した場合に `true` を返します。

# Imagick::deskewImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.3.0)

Imagick::deskewImage — 傾きを除去する

### 説明

public function 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::despeckleImage

(PECL imagick 2, PECL imagick 3)

Imagick::despeckleImage — 画像内のスペックルノイズを軽減する

### 説明

public function 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::destroy

(PECL imagick 2, PECL imagick 3)

Imagick::destroy — Imagick オブジェクトを破棄する

### 説明

public function Imagick::destroy(): bool

Imagick オブジェクトを破棄し、関連するリソースをすべて開放します。 このメソッドは非推奨です。かわりに Imagick::clear を使いましょう。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を返します。

# Imagick::displayImage

(PECL imagick 2, PECL imagick 3)

Imagick::displayImage — 画像を表示する

### 説明

public function Imagick::displayImage(string `$servername`): bool

このメソッドは、画像を X サーバーに表示します。

### パラメータ

`servername`

  X サーバーの名前。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::displayImages

(PECL imagick 2, PECL imagick 3)

Imagick::displayImages — 画像あるいは画像シーケンスを表示する

### 説明

public function Imagick::displayImages(string `$servername`): bool

画像あるいは画像シーケンスを X サーバーに表示します。

### パラメータ

`servername`

  X サーバーの名前。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::distortImage

(PECL imagick 2 >= 2.0.1, PECL imagick 3)

Imagick::distortImage — さまざまな方式で画像を歪める

### 説明

public function 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::blurImage() - blur (にじみ) フィルタを画像に追加する
- Imagick::motionBlurImage() - モーションブラーをシミュレートする
- Imagick::radialBlurImage() - 画像にラジアルブラーを施す

# Imagick::drawImage

(PECL imagick 2, PECL imagick 3)

Imagick::drawImage — 現在の画像上の ImagickDraw オブジェクトをレンダリングする

### 説明

public function Imagick::drawImage(ImagickDraw `$draw`): bool

現在の画像上の ImagickDraw オブジェクトをレンダリングします。

### パラメータ

`draw`

  画像をレンダリングする描画操作。

### 戻り値

成功した場合に `true` を返します。

# Imagick::edgeImage

(PECL imagick 2, PECL imagick 3)

Imagick::edgeImage — 画像の輪郭を強調する

### 説明

public function 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::embossImage

(PECL imagick 2, PECL imagick 3)

Imagick::embossImage — グレースケール画像に三次元効果を施して返す

### 説明

public function 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::encipherImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::encipherImage — 画像を暗号化する

### 説明

public function Imagick::encipherImage(string `$passphrase`): bool

プレーンなピクセル群を暗号化します。Imagick::decipherImage() で復号するまで、この画像は読めなくなります。 このメソッドは、ImageMagick バージョン 6.3.9 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

`passphrase`

  パスフレーズ。

### 戻り値

成功した場合に `true` を返します。

### 参考

- Imagick::decipherImage() - 画像を復号する

# Imagick::enhanceImage

(PECL imagick 2, PECL imagick 3)

Imagick::enhanceImage — ノイジーな画像の品質を向上させる

### 説明

public function 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::equalizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::equalizeImage — 画像ヒストグラムを均等化する

### 説明

public function 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::evaluateImage

(PECL imagick 2, PECL imagick 3)

Imagick::evaluateImage — 式を画像に適用する

### 説明

public function 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::exportImagePixels

(PECL imagick 2 >=2.3.0, PECL imagick 3)

Imagick::exportImagePixels — 画像の生のピクセルをエクスポートする

### 説明

public function 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::extentImage

(PECL imagick 2, PECL imagick 3)

Imagick::extentImage — 画像のサイズを設定する

### 説明

public function 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() - 画像の一部を抽出する

# Imagick::filter

(PECL imagick 3 >= 3.3.0)

Imagick::filter — カスタム畳み込みカーネルを画像に適用する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function Imagick::filter(ImagickKernel `$ImagickKernel`, int `$channel` = Imagick::CHANNEL_UNDEFINED): bool

カスタム畳み込みカーネルを画像に適用します。

### パラメータ

`ImagickKernel`

  単一のカーネル、または連結された一連のカーネルを表す ImagickKernel のインスタンス。

`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::flattenImages

(PECL imagick 2, PECL imagick 3)

Imagick::flattenImages — 画像シーケンスをマージする

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function Imagick::flattenImages(): Imagick

画像シーケンスをマージします。 これは、たとえば Photoshop のレイヤを単一の画像にまとめる場合などに便利です。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::flipImage

(PECL imagick 2, PECL imagick 3)

Imagick::flipImage — 垂直方向に反転した画像を作成する

### 説明

public function 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::floodFillPaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::floodFillPaintImage — 対象にマッチする任意のピクセルの値を変更する

### 説明

public function 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::flopImage

(PECL imagick 2, PECL imagick 3)

Imagick::flopImage — 水平方向に反転した画像を作成する

### 説明

public function 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() - 垂直方向に反転した画像を作成する

# Imagick::forwardFourierTransformImage

(PECL imagick 3 >= 3.3.0)

Imagick::forwardFourierTransformImage — 離散フーリエ変換 (DFT) を実行する

### 説明

public function Imagick::forwardFourierTransformimage(bool `$magnitude`): bool

画像の離散フーリエ変換 (DFT) を、振幅/位相のペアまたは実数/虚数の画像ペアとして実行します。

### パラメータ

`magnitude`

  true の場合は振幅/位相のペアとして返し、それ以外の場合は実数/虚数の画像ペアとして返します。

### 戻り値

成功した場合に `true` を返します。

### 例

例1 Imagick::forwardFourierTransformImage()

    <?php
    //forwardTransformImage のユーティリティ関数
    function createMask() {
        $draw = new \ImagickDraw();

        $draw->setStrokeOpacity(0);
        $draw->setStrokeColor('rgb(255, 255, 255)');
        $draw->setFillColor('rgb(255, 255, 255)');

        //y 軸上に、中心が x, y にあり
        //原点に接する円を描画する
        $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::frameImage

(PECL imagick 2, PECL imagick 3)

Imagick::frameImage — 三次元の枠線をシミュレートする

### 説明

public function 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::functionImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::functionImage — 画像に関数を適用する

### 説明

public function 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::fxImage

(PECL imagick 2, PECL imagick 3)

Imagick::fxImage — 式を画像の各ピクセルに適用する

### 説明

public function 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::gammaImage

(PECL imagick 2, PECL imagick 3)

Imagick::gammaImage — 画像をガンマ補正する

### 説明

public function 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::gaussianBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::gaussianBlurImage — 画像をぼかす

### 説明

public function 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::getColorspace

(PECL imagick 3)

Imagick::getColorspace — 色空間を取得する

### 説明

public function Imagick::getColorspace(): int

グローバル色空間の値を取得します。 このメソッドは、ImageMagick バージョン 6.5.7 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

整数値を返します。この値を COLORSPACE 定数 と比較することができます。

# Imagick::getCompression

(PECL imagick 2, PECL imagick 3)

Imagick::getCompression — オブジェクトの圧縮形式を取得する

### 説明

public function Imagick::getCompression(): int

オブジェクトの圧縮形式を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

圧縮定数を返します。

# Imagick::getCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::getCompressionQuality — オブジェクトの圧縮品質を取得する

### 説明

public function Imagick::getCompressionQuality(): int

オブジェクトの圧縮品質を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

圧縮品質を表す整数値を返します。

# Imagick::getCopyright

(PECL imagick 2, PECL imagick 3)

Imagick::getCopyright — ImageMagick API の著作権情報を文字列で返す

### 説明

public static function Imagick::getCopyright(): string

ImageMagick API の著作権情報を文字列で返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Imagemagick および Magickwand C API の著作権情報を含む文字列を返します。

# Imagick::getFilename

(PECL imagick 2, PECL imagick 3)

Imagick::getFilename — 画像シーケンスに関連付けられたファイル名を取得する

### 説明

public function Imagick::getFilename(): string

画像シーケンスに関連付けられたファイル名を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に文字列を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getFont

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::getFont — フォントを取得する

### 説明

public function Imagick::getFont(): string

オブジェクトのフォントプロパティを返します。 このメソッドは、ImageMagick バージョン 6.3.7 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

フォント名を表す文字列を返します。フォントが設定されていない場合は `false` を返します。

### 参考

- Imagick::setFont() - フォントを設定する
- ImagickDraw::setFont() - テキストによる注記を行う際に使用するフォントを設定する
- ImagickDraw::getFont() - フォントを返す

# Imagick::getFormat

(PECL imagick 2, PECL imagick 3)

Imagick::getFormat — Imagick オブジェクトのフォーマットを取得する

### 説明

public function Imagick::getFormat(): string

Imagick オブジェクトのフォーマットを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像フォーマットを返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getGravity

(PECL imagick 2, PECL imagick 3)

Imagick::getGravity — gravity を取得する

### 説明

public function Imagick::getGravity(): int

Imagick オブジェクトのグローバル gravity プロパティを取得します。 このメソッドは、ImageMagick バージョン 6.4.0 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

gravity プロパティを返します。 gravity 定数 の一覧を参照ください。

# Imagick::getHomeURL

(PECL imagick 2, PECL imagick 3)

Imagick::getHomeURL — ImageMagick のホーム URL を返す

### 説明

public static function Imagick::getHomeURL(): string

ImageMagick のホーム URL を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

imagemagick のホームページへのリンクを返します。

# Imagick::getImage

(PECL imagick 2, PECL imagick 3)

Imagick::getImage — 新しい Imagick オブジェクトを返す

### 説明

public function Imagick::getImage(): Imagick

現在の画像シーケンスを使用した新しい Imagick オブジェクトを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

現在の画像シーケンスを使用した新しい Imagick オブジェクトを返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageAlphaChannel

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageAlphaChannel — 画像がアルファチャネルを持つかを調べる

### 説明

public function Imagick::getImageAlphaChannel(): bool

画像がアルファチャネルを持つかを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像がアルファチャネル値を持つ場合は `true` を返します。 持たない場合 つまり、画像が RGBA ではなく RGB の場合。 または CMYKA ではなく、 CMYK である場合には、 `false` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

### 変更履歴

バージョン | 説明
--- | ---
PECL imagick 3.6.0 | bool を返すようになりました。 これより前のバージョンでは、int を返していました。

# Imagick::getImageArtifact

(PECL imagick 3)

Imagick::getImageArtifact — 画像のアーチファクトを取得する

### 説明

public function Imagick::getImageArtifact(string `$artifact`): string

画像に関連づけられたアーチファクトを取得します。プロパティとアーチファクトの違いは、 プロパティは public であるのに対してアーチファクトは private であるという点です。 このメソッドは、ImageMagick バージョン 6.5.7 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

`artifact`

  アーチファクトの名前。

### 戻り値

成功した場合にアーチファクトの値を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

### 参考

- Imagick::setImageArtifact() - 画像のアーチファクトを設定する
- Imagick::deleteImageArtifact() - 画像のアーチファクトを削除する

# Imagick::getImageAttribute

(PECL imagick 2, PECL imagick 3)

Imagick::getImageAttribute — 名前を指定して属性を返す

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function Imagick::getImageAttribute(string `$key`): string

名前を指定して属性を返します。

### パラメータ

`key`

  取得する属性のキー。

### 戻り値

# Imagick::getImageBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBackgroundColor — 画像の背景色を返す

### 説明

public function Imagick::getImageBackgroundColor(): ImagickPixel

画像の背景色を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像の背景色を設定した ImagickPixel を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBlob — 画像シーケンスを blob で返す

### 説明

public function Imagick::getImageBlob(): string

画像フォーマットを直接記憶します。 これは、画像シーケンスを文字列で返します。 画像のフォーマットによって、返される blob の形式 (GIF, JPEG, PNG, など) が決まります。 別の画像フォーマットを返すには Imagick::SetImageFormat() を使用します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像を含む文字列を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageBluePrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBluePrimary — 青が一番強い点を返す

### 説明

public function Imagick::getImageBluePrimary(): array

青が一番強い点を返します。

### パラメータ

`x`

  青が一番強い点の x 座標。

`y`

  青が一番強い点の y 座標。

### 戻り値

"x" 座標および "y" 座標を含む配列を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageBorderColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageBorderColor — 画像の前景色を返す

### 説明

public function Imagick::getImageBorderColor(): ImagickPixel

画像の前景色を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageChannelDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelDepth — 特定の画像チャネルの深度を返す

### 説明

public function Imagick::getImageChannelDepth(int `$channel`): int

特定の画像チャネルの深度を返します。

### パラメータ

`channel`

  そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは `Imagick::CHANNEL_DEFAULT` です。 チャネル定数 の一覧を参照ください。

### 戻り値

成功した場合に `true` を返します。

# Imagick::getImageChannelDistortion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelDistortion — 画像のチャネルを再構築した画像と比較する

### 説明

public function Imagick::getImageChannelDistortion(Imagick `$reference`, int `$channel`, int `$metric`): float

ひとつあるいは複数のチャネルの内容を再構築した画像と比較し、 指定した歪み係数を返します。

### パラメータ

`reference`

  比較する Imagick オブジェクト。

`channel`

  チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

`metric`

  メトリック型定数 のいずれか。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageChannelDistortions

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageChannelDistortions — チャネルの歪みを取得する

### 説明

public function 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::getImageChannelExtrema

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelExtrema — ひとつあるいは複数の画像チャネルの極値を取得する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function Imagick::getImageChannelExtrema(int `$channel`): array

ひとつあるいは複数の画像チャネルの極値を取得します。 戻り値は連想配列で、"minima" および "maxima" というキーを含みます。

### パラメータ

`channel`

  チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageChannelKurtosis

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageChannelKurtosis — getImageChannelKurtosis

### 説明

public function Imagick::getImageChannelKurtosis(int `$channel` = Imagick::CHANNEL_DEFAULT): array

指定したチャネルの尖度と歪度を取得します。このメソッドは、ImageMagick バージョン 6.4.9 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

`channel`

  そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは `Imagick::CHANNEL_DEFAULT` です。 チャネル定数 の一覧を参照ください。

### 戻り値

`kurtosis` と `skewness` を要素に持つ配列を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageChannelMean

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelMean — 平均値と標準偏差を取得する

### 説明

public function Imagick::getImageChannelMean(int `$channel`): array

ひとつあるいは複数の画像チャネルの平均値および標準偏差を取得します。

### パラメータ

`channel`

  チャネルモードに対応したチャネル定数を指定します。 複数のチャネルに適用するには、 ビット演算子でチャネル型定数を組み合わせます。 チャネル定数 の一覧を参照ください。

### 戻り値

"mean" および "standardDeviation" というキーを含む配列を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageChannelRange

(PECL imagick 2 >= 2.2.1, PECL imagick 3)

Imagick::getImageChannelRange — チャネルの範囲を取得する

### 説明

public function Imagick::getImageChannelRange(int `$channel`): array

ひとつあるいは複数のチャネルの範囲を取得します。 このメソッドは、ImageMagick バージョン 6.4.0 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

`channel`

  そのモードで有効なチャネル定数を指定します。 複数のチャネルを適用するには、チャネル定数 をビット演算子で組み合わせます。デフォルトは `Imagick::CHANNEL_DEFAULT` です。 チャネル定数 の一覧を参照ください。

### 戻り値

チャネルの minima および maxima の値を含む配列を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageChannelStatistics

(PECL imagick 2, PECL imagick 3)

Imagick::getImageChannelStatistics — 画像の各チャネルの統計情報を返す

### 説明

public function Imagick::getImageChannelStatistics(): array

画像の各チャネルの統計情報を返します。 この情報に含まれるのは、チャネルの深度、最小値と最大値、 平均値、そして標準偏差です。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を返します。

# Imagick::getImageClipMask

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageClipMask — 画像のクリップマスクを取得する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function Imagick::getImageClipMask(): Imagick

画像のクリップマスクを含む Imagick オブジェクトを返します。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像のクリップマスクを含む Imagick オブジェクトを返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageColormapColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColormapColor — 指定したインデックスに対応する色マップ上の色を返す

### 説明

public function Imagick::getImageColormapColor(int `$index`): ImagickPixel

指定したインデックスに対応する色マップ上の色を返します。

### パラメータ

`index`

  画像の色マップ内のオフセット。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageColors

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColors — 画像で使われている色の数を取得する

### 説明

public function Imagick::getImageColors(): int

画像で使われている色の数を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像で使われているユニークな色の数を int で返します。

# Imagick::getImageColorspace

(PECL imagick 2, PECL imagick 3)

Imagick::getImageColorspace — 画像の色空間を取得する

### 説明

public function Imagick::getImageColorspace(): int

画像の色空間を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

COLORSPACE 定数 と比較できる整数を返します。

# Imagick::getImageCompose

(PECL imagick 2, PECL imagick 3)

Imagick::getImageCompose — 画像の合成演算子を返す

### 説明

public function Imagick::getImageCompose(): int

画像に関連付けられている合成演算子を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を返します。

# Imagick::getImageCompression

(PECL imagick 3 >= 3.3.0)

Imagick::getImageCompression — 現在の画像の圧縮形式を取得する

### 説明

public function Imagick::getImageCompression(): int

現在の画像の圧縮形式を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

圧縮形式を表す定数を返します。

# Imagick::getImageCompressionQuality

(PECL imagick 2 >= 2.2.2, PECL imagick 3)

Imagick::getImageCompressionQuality — 現在の画像の圧縮品質を取得する

### 説明

public function Imagick::getImageCompressionQuality(): int

現在の画像の圧縮品質を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像の圧縮品質を表す整数値を返します。

# Imagick::getImageDelay

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDelay — 画像の遅延を取得する

### 説明

public function Imagick::getImageDelay(): int

画像の遅延を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像の遅延を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDepth — 画像の深度を取得する

### 説明

public function Imagick::getImageDepth(): int

画像の深度を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像の深度を返します。

# Imagick::getImageDispose

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDispose — 画像の配置方法を取得する

### 説明

public function Imagick::getImageDispose(): int

画像の配置方法を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に配置方法を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageDistortion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageDistortion — ある画像と再構築した画像を比較する

### 説明

public function Imagick::getImageDistortion(MagickWand `$reference`, int `$metric`): float

ある画像と再構築した画像を比較し、 指定した歪み係数を返します。

### パラメータ

`reference`

  比較する Imagick オブジェクト。

`metric`

  メトリック型定数 のいずれか。

### 戻り値

その画像で使用する歪み係数 (あるいはその推測値) を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageExtrema

(PECL imagick 2, PECL imagick 3)

Imagick::getImageExtrema — 画像の極値を取得する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function Imagick::getImageExtrema(): array

画像の極値を取得します。 "min" および "max" というキーを持つ連想配列を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

"min" および "max" というキーを持つ連想配列を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageFilename

(PECL imagick 2, PECL imagick 3)

Imagick::getImageFilename — シーケンス内の特定の画像のファイル名を返す

### 説明

public function Imagick::getImageFilename(): string

シーケンス内の特定の画像のファイル名を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像のファイル名を文字列で返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageFormat

(PECL imagick 2, PECL imagick 3)

Imagick::getImageFormat — シーケンス内の特定の画像のフォーマットを返す

### 説明

public function Imagick::getImageFormat(): string

シーケンス内の特定の画像のフォーマットを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合は画像のフォーマットを文字列で返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageGamma

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGamma — 画像のガンマを取得する

### 説明

public function Imagick::getImageGamma(): float

画像のガンマを取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合にガンマを返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageGeometry

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGeometry — 幅と高さを連想配列で取得する

### 説明

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

# Imagick::getImageGravity

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageGravity — 画像の gravity を取得する

### 説明

public function Imagick::getImageGravity(): int

画像の原罪の current 値を取得します。 Imagick::getGravity() とは異なり、 このメソッドは原罪の画像シーケンスで定義された gravity を返します。 このメソッドは、ImageMagick バージョン 6.4.4 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像の property プロパティを返します。 gravity 定数 の一覧を参照ください。

# Imagick::getImageGreenPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageGreenPrimary — 緑が一番強い点を返す

### 説明

public function Imagick::getImageGreenPrimary(): array

緑が一番強い点を返します。"x" および "y" というキーを持つ配列を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に "x" および "y" というキーを持つ配列を返します。 失敗した場合は ImagickException をスローします。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageHeight

(PECL imagick 2, PECL imagick 3)

Imagick::getImageHeight — 画像の高さを返す

### 説明

public function Imagick::getImageHeight(): int

画像の高さを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像の高さをピクセル数で返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageHistogram

(PECL imagick 2, PECL imagick 3)

Imagick::getImageHistogram — 画像のヒストグラムを取得する

### 説明

public function 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::getImageIndex

(PECL imagick 2, PECL imagick 3)

Imagick::getImageIndex — 現在アクティブな画像のインデックスを取得する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function Imagick::getImageIndex(): int

Imagick オブジェクト内で現在アクティブな画像のインデックスを取得します。 このメソッドは非推奨です。 Imagick::getIteratorIndex() を参照ください。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

スタック内の画像のインデックスを表す整数値を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::getImageInterlaceScheme — 画像のインターレース手法を取得する

### 説明

public function Imagick::getImageInterlaceScheme(): int

画像のインターレース手法を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に画像のインターレース手法を返します。 エラー時に ImagickException をスローします。

# Imagick::getImageInterpolateMethod

(PECL imagick 2, PECL imagick 3)

Imagick::getImageInterpolateMethod — 画像の補間方式を返す

### 説明

public function Imagick::getImageInterpolateMethod(): int

指定した画像の補間方式を返します。 方式は `Imagick::INTERPOLATE_*` 定数のいずれかで指定します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に補間方式を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageIterations

(PECL imagick 2, PECL imagick 3)

Imagick::getImageIterations — 画像の反復を取得する

### 説明

public function Imagick::getImageIterations(): int

画像の反復を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像の反復を表す整数値を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageLength

(PECL imagick 2, PECL imagick 3)

Imagick::getImageLength — 画像の長さをバイト数で取得する

### 説明

public function Imagick::getImageLength(): int

画像の長さをバイト数で返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

現在の画像のサイズを整数値で返します。

### 例

例1 Imagick::getImageLength() の使用法

画像の長さをバイト数で取得します。

    <?php
    $image = new Imagick('test.jpg');
    echo $image->getImageLength() . ' bytes';
    ?>

# Imagick::getImageMatte

(PECL imagick 2, PECL imagick 3)

Imagick::getImageMatte — 画像がマットチャネルを持っているかどうかを返す

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function Imagick::getImageMatte(): bool

画像がマットチャネルを持っている場合に `true`、 そうでない場合に false を返します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を返します。

# Imagick::getImageMatteColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImageMatteColor — 画像のマット色を返す

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function Imagick::getImageMatteColor(): ImagickPixel

画像のマット色を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に ImagickPixel オブジェクトを返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageMimeType

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::getImageMimeType — 画像の MIME タイプを返す

### 説明

public function Imagick::getImageMimeType(): string

画像の MIME タイプを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# Imagick::getImageOrientation

(PECL imagick 2, PECL imagick 3)

Imagick::getImageOrientation — 画像の方向を取得する

### 説明

public function Imagick::getImageOrientation(): int

画像の方向を取得します。戻り値は 方向定数 のいずれかとなります。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に整数値を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImagePage

(PECL imagick 2, PECL imagick 3)

Imagick::getImagePage — ページのジオメトリを返す

### 説明

public function Imagick::getImagePage(): array

画像のページジオメトリを配列で返します。配列のキーは "width"、"height"、"x" および "y" です。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像のページジオメトリを配列で返します。配列のキーは "width"、"height"、"x" および "y" です。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImagePixelColor

(PECL imagick 2, PECL imagick 3)

Imagick::getImagePixelColor — 指定したピクセルの色を返す

### 説明

public function Imagick::getImagePixelColor(int `$x`, int `$y`): ImagickPixel

指定したピクセルの色を返します。

### パラメータ

`x`

  ピクセルの x 座標。

`y`

  ピクセルの y 座標。

### 戻り値

指定した座標の色を表す ImagickPixel のインスタンスを返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProfile — 指定した名前の画像プロファイルを返す

### 説明

public function Imagick::getImageProfile(string `$name`): string

指定した名前の画像プロファイルを返します。

### パラメータ

`name`

  返したいプロファイルの名前。

### 戻り値

画像プロファイルを含む文字列を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageProfiles

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProfiles — 画像プロファイルを返す

### 説明

public function Imagick::getImageProfiles(string `$pattern` = "*", bool `$include_values` = `true`): array

関連付けられているプロファイルのうち、パターンにマッチするものをすべて返します。 二番目の引数を `false` にすると、プロファイルの名前だけを返します。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

`pattern`

  プロファイル名のパターン。

`include_values`

  プロファイル名のみを返すかどうか。`false` の場合は、プロファイル名のみを返します。

### 戻り値

画像のプロファイルあるいはプロファイル名を含む連想配列を返します。

# Imagick::getImageProperties

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProperties — 画像のプロパティを返す

### 説明

public function 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::getImageProperty

(PECL imagick 2, PECL imagick 3)

Imagick::getImageProperty — 指定した名前の画像のプロパティを返す

### 説明

public function 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::getImageRedPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRedPrimary — 赤が一番強い点を返す

### 説明

public function Imagick::getImageRedPrimary(): array

赤が一番強い点を返します。"x" および "y" というキーを持つ配列を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

赤が一番強い点を "x" および "y" というキーを持つ配列で返します。 エラー時に ImagickException をスローします。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageRegion

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRegion — 画像の一部を抽出する

### 説明

public function Imagick::getImageRegion(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): Imagick

画像の一部を抽出し、新しい Imagick オブジェクトとして返します。

### パラメータ

`width`

  抽出する範囲の幅。

`height`

  抽出する範囲の高さ。

`x`

  抽出する範囲の左上の X 座標。

`y`

  抽出する範囲の左上の Y 座標。

### 戻り値

画像の一部を抽出し、新しい wand として返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageRenderingIntent

(PECL imagick 2, PECL imagick 3)

Imagick::getImageRenderingIntent — 画像のレンダリング方向を取得する

### 説明

public function Imagick::getImageRenderingIntent(): int

画像のレンダリング方向を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像の レンダリング方向 を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageResolution

(PECL imagick 2, PECL imagick 3)

Imagick::getImageResolution — 画像の X 方向と Y 方向の解像度を取得する

### 説明

public function Imagick::getImageResolution(): array

X 方向および Y 方向の解像度を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

解像度を配列で返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImagesBlob

(PECL imagick 2, PECL imagick 3)

Imagick::getImagesBlob — すべての画像シーケンスを blob で返す

### 説明

public function Imagick::getImagesBlob(): string

メモリ上の画像フォーマットを直接操作します。 すべての画像シーケンスを文字列として返します。 画像のフォーマット (GIF, JPEG, PNG など) に応じて返される blob の形式も異なります。 別の画像フォーマットで返すには Imagick::setImageFormat() を使用します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像を文字列で返します。失敗した場合は ImagickException をスローします。

# Imagick::getImageScene

(PECL imagick 2, PECL imagick 3)

Imagick::getImageScene — 画像のシーンを取得する

### 説明

public function Imagick::getImageScene(): int

画像のシーンを取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像のシーンを返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageSignature

(PECL imagick 2, PECL imagick 3)

Imagick::getImageSignature — SHA-256 メッセージダイジェストを生成する

### 説明

public function Imagick::getImageSignature(): string

画像ピクセルストリームの SHA-256 メッセージダイジェストを生成します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

そのファイルの SHA-256 ハッシュを文字列で返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageSize

(PECL imagick 2, PECL imagick 3)

Imagick::getImageSize — 画像の長さをバイト数で返す

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function Imagick::getImageSize(): int

画像の長さをバイト数で返します。 非推奨です。かわりに Imagick::getImageLength() を使いましょう。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

現在の画像のサイズをバイト数で返します。

# Imagick::getImageTicksPerSecond

(PECL imagick 2, PECL imagick 3)

Imagick::getImageTicksPerSecond — 画像の ticks-per-second を取得する

### 説明

public function Imagick::getImageTicksPerSecond(): int

画像の ticks-per-second を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像の ticks-per-second を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageTotalInkDensity

(PECL imagick 2, PECL imagick 3)

Imagick::getImageTotalInkDensity — 画像の総インク密度を取得する

### 説明

public function Imagick::getImageTotalInkDensity(): float

画像の総インク密度を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像の総インク密度を返します。 エラー時に ImagickException をスローします。

# Imagick::getImageType

(PECL imagick 2, PECL imagick 3)

Imagick::getImageType — 画像の型を取得する

### 説明

public function 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::getImageUnits

(PECL imagick 2, PECL imagick 3)

Imagick::getImageUnits — 画像の解像度の単位を取得する

### 説明

public function Imagick::getImageUnits(): int

画像の解像度の単位を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像の解像度の単位を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageVirtualPixelMethod

(PECL imagick 2, PECL imagick 3)

Imagick::getImageVirtualPixelMethod — 仮想ピクセルメソッドを取得する

### 説明

public function Imagick::getImageVirtualPixelMethod(): int

指定した画像の仮想ピクセルメソッドを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に仮想ピクセルメソッドを返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageWhitePoint

(PECL imagick 2, PECL imagick 3)

Imagick::getImageWhitePoint — 色度が白い点を返す

### 説明

public function Imagick::getImageWhitePoint(): array

色度が白い点を返します。 "x" および "y" というキーを持つ連想配列となります。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

色度が白い点を返します。 "x" および "y" というキーを持つ連想配列となります。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getImageWidth

(PECL imagick 2, PECL imagick 3)

Imagick::getImageWidth — 画像の幅を返す

### 説明

public function Imagick::getImageWidth(): int

画像の幅を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像の幅を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::getInterlaceScheme — オブジェクトのインターレース方式を取得する

### 説明

public function Imagick::getInterlaceScheme(): int

オブジェクトのインターレース方式を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

インターレース方式 を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getIteratorIndex

(PECL imagick 2, PECL imagick 3)

Imagick::getIteratorIndex — 現在アクティブな画像のインデックスを取得する

### 説明

public function 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::getNumberImages

(PECL imagick 2, PECL imagick 3)

Imagick::getNumberImages — オブジェクト内の画像の数を返す

### 説明

public function Imagick::getNumberImages(): int

Imagick オブジェクトに関連付けられている画像の数を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Imagick オブジェクトに関連付けられている画像の数を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getOption

(PECL imagick 2, PECL imagick 3)

Imagick::getOption — 指定したキーに対応する値を返す

### 説明

public function Imagick::getOption(string `$key`): string

オブジェクト内の指定したキーに対応する値を返します。

### パラメータ

`key`

  オプションの名前。

### 戻り値

指定したキーに対応する値を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getPackageName

(PECL imagick 2, PECL imagick 3)

Imagick::getPackageName — ImageMagick パッケージ名を返す

### 説明

public static function Imagick::getPackageName(): string

ImageMagick パッケージ名を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

ImageMagick パッケージ名を文字列で返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getPage

(PECL imagick 2, PECL imagick 3)

Imagick::getPage — ページのジオメトリを返す

### 説明

public function Imagick::getPage(): array

Imagick オブジェクトに関連付けられたページのジオメトリを返します。 "width"、"height"、"x" そして "y" というキーを持つ連想配列となります。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Imagick オブジェクトに関連付けられたページのジオメトリを返します。 "width"、"height"、"x" そして "y" というキーを持つ連想配列となります。 エラー時に ImagickException をスローします。

# Imagick::getPixelIterator

(PECL imagick 2, PECL imagick 3)

Imagick::getPixelIterator — MagickPixelIterator を返す

### 説明

public function 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;
    }

    ?>

# Imagick::getPixelRegionIterator

(PECL imagick 2, PECL imagick 3)

Imagick::getPixelRegionIterator — 画像セクションの ImagickPixelIterator を取得する

### 説明

public function 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::getPointSize

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::getPointSize — ポイントサイズを取得する

### 説明

public function Imagick::getPointSize(): float

オブジェクトのポイントサイズプロパティを返します。 このメソッドは、ImageMagick バージョン 6.3.7 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

ポイントサイズを表す float 型の値を返します。

### 参考

- Imagick::setPointSize() - ポイントサイズを設定する

# Imagick::getQuantum

(PECL imagick 3 >= 3.3.0)

Imagick::getQuantum — ImageMagick の quantum range を返す

### 説明

public static function Imagick::getQuantum(): int

ImageMagick の quantum range を返します。HDRI が有効な場合は型が float になり、そうでない場合は int になります。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# Imagick::getQuantumDepth

(PECL imagick 2, PECL imagick 3)

Imagick::getQuantumDepth — quantum depth を取得する

### 説明

public static function Imagick::getQuantumDepth(): array

Imagick quantum depth を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

`"quantumDepthLong"` と `"quantumDepthString"` をキーとして持つ配列を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getQuantumRange

(PECL imagick 2, PECL imagick 3)

Imagick::getQuantumRange — Imagick quantum range を返す

### 説明

public static function Imagick::getQuantumRange(): array

Imagick インスタンスの quantum range を文字列で返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

quantum range を連想配列で返します。 int (`"quantumRangeLong"`) と string (`"quantumRangeString"`) が含まれます。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::getRegistry — StringRegistry エントリを取得する

### 説明

public static function Imagick::getRegistry(string `$key`): string

指定されたキーの StringRegistry エントリを取得します。 設定されていない場合は false を返します。

### パラメータ

`key`

  取得するエントリ。

### 戻り値

# Imagick::getReleaseDate

(PECL imagick 2, PECL imagick 3)

Imagick::getReleaseDate — ImageMagick のリリース日を返す

### 説明

public static function Imagick::getReleaseDate(): string

ImageMagick のリリース日を文字列で返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

ImageMagick のリリース日を文字列で返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getResource

(PECL imagick 2, PECL imagick 3)

Imagick::getResource — 指定したリソースのメモリ使用状況を返す

### 説明

public static function Imagick::getResource(int `$type`): int

指定したリソースのメモリ使用状況をメガバイト単位で返します。

### パラメータ

`type`

  リソース型定数 の一覧を参照ください。

### 戻り値

指定したリソースのメモリ使用状況をメガバイト単位で返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getResourceLimit

(PECL imagick 2, PECL imagick 3)

Imagick::getResourceLimit — 指定したリソースの制限を返す

### 説明

public static function Imagick::getResourceLimit(int `$type`): int

指定したリソースの制限を返します。

### パラメータ

`type`

  リソース型定数 のうちのひとつ。

### 戻り値

指定したリソースの制限を返します。 単位は制限されるリソースのタイプに依存します。

### エラー / 例外

エラー時に ImagickException をスローします。

### 参考

- Imagick::setResourceLimit() - 特定のリソースの制限を設定する

# Imagick::getSamplingFactors

(PECL imagick 2, PECL imagick 3)

Imagick::getSamplingFactors — 水平方向および垂直方向のサンプリング係数を取得する

### 説明

public function Imagick::getSamplingFactors(): array

水平方向および垂直方向のサンプリング係数を取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

画像の水平方向および垂直方向のサンプリング係数を含む連想配列を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getSize

(PECL imagick 2, PECL imagick 3)

Imagick::getSize — Imagick オブジェクトに関連付けられたサイズを返す

### 説明

public function Imagick::getSize(): array

Imagick::setSize() で以前設定された、Imagick オブジェクトに関連付けられたサイズをピクセル単位で取得します。

> 注意:

> このメソッドは Imagick::setSize() を使用して設定されたサイズを返すだけです。実際の画像の幅/高さを取得するには、Imagick::getImageWidth() と Imagick::getImageHeight() を使用してください。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Imagick オブジェクトに関連付けられたサイズを、"columns" と "rows" のキーを持つ配列として返します。

### 例

例1 200x400 の RAW RGB 画像を 400x800 にスケーリングした後のサイズの取得 (幅/高さとの比較)

    <?php
    // まずサイズを設定してから RAW 画像を読み込む
    $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::getSizeOffset

(PECL imagick 2, PECL imagick 3)

Imagick::getSizeOffset — サイズのオフセットを返す

### 説明

public function Imagick::getSizeOffset(): int

Imagick オブジェクトのサイズのオフセットを返します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Imagick オブジェクトのサイズのオフセットを返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::getVersion

(PECL imagick 2, PECL imagick 3)

Imagick::getVersion — ImageMagick API のバージョンを返す

### 説明

public static function Imagick::getVersion(): array

ImageMagick API のバージョンを文字列と数値で返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

ImageMagick API のバージョンを文字列と数値で返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::haldClutImage

(PECL imagick 3)

Imagick::haldClutImage — 画像内の色を置換する

### 説明

public function 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::hasNextImage

(PECL imagick 2, PECL imagick 3)

Imagick::hasNextImage — オブジェクトが次の画像を保持しているかどうかを調べる

### 説明

public function Imagick::hasNextImage(): bool

リスト内でひとつ先に進んだときにまだオブジェクトが画像を保持していれば `true` を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

リスト内でひとつ先に進んだときにまだオブジェクトが画像を保持していれば `true`、していなければ `false` を返します。

# Imagick::hasPreviousImage

(PECL imagick 2, PECL imagick 3)

Imagick::hasPreviousImage — オブジェクトが前の画像を保持しているかどうかを調べる

### 説明

public function Imagick::hasPreviousImage(): bool

リスト内で逆方向にひとつ進んだときにまだオブジェクトが画像を保持していれば `true` を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

リスト内で逆方向にひとつ進んだときにまだオブジェクトが画像を保持していれば `true`、していなければ `false` を返します。

# Imagick::identifyFormat

(PECL imagick 3 >= 3.3.0)

Imagick::identifyFormat — 画像の詳細情報で文字列をフォーマットする

### 説明

public function Imagick::identifyFormat(string `$embedText`): string|false

埋め込まれたフォーマット文字を適切な画像プロパティに置き換え、解釈されたテキストを返します。エスケープシーケンスについては http://www.imagemagick.org/script/escape.php を参照してください。

### パラメータ

`embedText`

  フォーマットシーケンスを含む文字列。例: "Trim box: %@ number of unique colors: %k"。

### 戻り値

フォーマットされた文字列を返します。失敗した場合に `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::identifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::identifyImage — 画像を識別し、属性を取得する

### 説明

public function 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::implodeImage

(PECL imagick 2, PECL imagick 3)

Imagick::implodeImage — 新しい画像をコピーとして作成する

### 説明

public function 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::importImagePixels

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::importImagePixels — 画像のピクセルをインポートする

### 説明

public function 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::inverseFourierTransformImage

(PECL imagick 3 >= 3.3.0)

Imagick::inverseFourierTransformImage — 逆離散フーリエ変換 (DFT) を実行する

### 説明

public function Imagick::inverseFourierTransformImage(Imagick `$complement`, bool `$magnitude`): bool

画像の逆離散フーリエ変換 (DFT) を、振幅/位相のペアまたは実数/虚数の画像ペアとして実行します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`complement`

  振幅/位相または実数/虚数の画像ペアを構成するために、この画像と組み合わせる2番目の画像。

`magnitude`

  true の場合は振幅/位相のペアとして結合し、それ以外の場合は実数/虚数の画像ペアとして結合します。

### 戻り値

成功した場合に `true` を返します。

# Imagick::labelImage

(PECL imagick 2, PECL imagick 3)

Imagick::labelImage — ラベルを画像に追加する

### 説明

public function Imagick::labelImage(string `$label`): bool

ラベルを画像に追加します。

### パラメータ

`label`

  追加するラベル。

### 戻り値

成功した場合に `true` を返します。

# Imagick::levelImage

(PECL imagick 2, PECL imagick 3)

Imagick::levelImage — 画像のレベルを調節する

### 説明

public function 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::linearStretchImage

(PECL imagick 2, PECL imagick 3)

Imagick::linearStretchImage — 画像の輝度を引き伸ばして飽和させる

### 説明

public function 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::liquidRescaleImage

(PECL imagick 2 >= 2.2.0, PECL imagick 3)

Imagick::liquidRescaleImage — 画像を動かす

### 説明

public function 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() - 画像のサイズを変更する

# Imagick::listRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::listRegistry — すべてのレジストリ設定を一覧表示する

### 説明

public static function Imagick::listRegistry(): array

すべてのレジストリ設定を一覧表示します。 レジストリ内のすべてのキーと値のペアを含む配列を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

レジストリのキーと値を含む配列を返します。

# Imagick::magnifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::magnifyImage — 画像を 2 倍に比例拡大する

### 説明

public function 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::mapImage

(PECL imagick 2, PECL imagick 3)

Imagick::mapImage — 画像の色を、参照画像の中の最も近い色に置き換える

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function Imagick::mapImage(Imagick `$map`, bool `$dither`): bool

### パラメータ

`map`

`dither`

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::matteFloodfillImage

(PECL imagick 2, PECL imagick 3)

Imagick::matteFloodfillImage — 色の透明度を変更する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function 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::medianFilterImage

(PECL imagick 2, PECL imagick 3)

Imagick::medianFilterImage — デジタルフィルタを適用する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function 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::mergeImageLayers

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::mergeImageLayers — 画像のレイヤーをマージする

### 説明

public function 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($imagePath1));

        $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::minifyImage

(PECL imagick 2, PECL imagick 3)

Imagick::minifyImage — 画像をその半分のサイズに比例縮小する

### 説明

public function Imagick::minifyImage(): bool

画像のサイズを元の半分に比例縮小します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を返します。

# Imagick::modulateImage

(PECL imagick 2, PECL imagick 3)

Imagick::modulateImage — 明度、飽和度、色相を制御する

### 説明

public function 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::montageImage

(PECL imagick 2, PECL imagick 3)

Imagick::montageImage — 合成画像を作成する

### 説明

public function 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::morphImages

(PECL imagick 2, PECL imagick 3)

Imagick::morphImages — 複数の画像をモーフィングする

### 説明

public function Imagick::morphImages(int `$number_frames`): Imagick

複数の画像をモーフィングします。 それぞれの画像のピクセルとサイズが線形補間され、 ある画像から次の画像へと変形していきます。

### パラメータ

`number_frames`

  生成する中間画像の数。

### 戻り値

このメソッドは、成功した場合に新しい Imagick オブジェクトを返します。 エラー時に ImagickException をスローします。

# Imagick::morphology

(PECL imagick 3 >= 3.3.0)

Imagick::morphology — 指定されたモルフォロジーメソッドに従い、ユーザー指定のカーネルを画像に適用する

### 説明

public function Imagick::morphology(
int `$morphologyMethod`,
int `$iterations`,
ImagickKernel `$ImagickKernel`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

指定されたモルフォロジーメソッドに従い、ユーザー指定のカーネルを画像に適用します。

### パラメータ

`morphologyMethod`

  使用するモルフォロジーメソッド。\Imagick::MORPHOLOGY_* 定数のいずれか。

`iterations`

  モルフォロジー関数を適用する回数。-1 を指定すると、変化がなくなるまでループします。この値がどのように適用されるかは、モルフォロジーメソッドに依存する場合があります。通常、この値は 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

            // 左上のピクセルは黒でなければならない
            // 右下のピクセルは白でなければならない
            // 残りは問わない

            $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 Chebyshev カーネルによる Distance 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 Manhattan カーネルによる Distance 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 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 Euclidean カーネルによる Distance 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
            // 結果として、'Open' が輪郭を滑らかにし、鋭い角を丸め、使用した形状より小さい部分を除去したことがわかります。また、細い橋状の部分を切断（'open'）します。
            $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
            // 結果として、'Open' が輪郭を滑らかにし、鋭い角を丸め、使用した形状より小さい部分を除去したことがわかります。また、細い橋状の部分を切断（'open'）します。

            $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
            //'Close' メソッドの基本的な用途は、カーネル '構造要素' のサイズ程度の 'holes'（穴）や 'gaps'（隙間）を縮小または除去することです。つまり、そのサイズ程度の背景部分を '閉じ' ます。
            $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
            //'Close' メソッドの基本的な用途は、カーネル '構造要素' のサイズ程度の 'holes'（穴）や 'gaps'（隙間）を縮小または除去することです。つまり、そのサイズ程度の背景部分を '閉じ' ます。
            $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 'TopHat' メソッド、より正確には 'White Top Hat' は、Opening によって除去されたピクセル、つまり角を丸めるために除去されたピクセルや形状間の接続部分を返します。 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 'BottomHat' メソッドは、'Black TopHat' とも呼ばれ、Closing によって画像に追加されるピクセルです。つまり、'holes'、'gaps'、'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();
            //右端から 3 ピクセル以内にあるすべてのピクセルを検出する
            $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 凸包を生成する Thicken Imagick::morphology()

    <?php
            $canvas = $this->getCharacterOutline();
            $diamondKernel = \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DIAMOND, "1");
            $convexKernel =  \ImagickKernel::fromBuiltIn(\Imagick::KERNEL_CONVEX_HULL, "");

            // thicken モルフォロジーは小さな隙間を処理できないため、
            // close モルフォロジーで閉じる。
            $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 反復モルフォロジー 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 画像のシルエットを取得するヘルパー関数 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::mosaicImages

(PECL imagick 2, PECL imagick 3)

Imagick::mosaicImages — 画像からモザイクを作成する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function Imagick::mosaicImages(): Imagick

画像シーケンスをはめ込み合成して単一の画像にします。 シーケンス内の各画像を、画像のページオフセットで指定した位置に合成したものを返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を返します。

# Imagick::motionBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::motionBlurImage — モーションブラーをシミュレートする

### 説明

public function 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::negateImage

(PECL imagick 2, PECL imagick 3)

Imagick::negateImage — 画像の色を打ち消す

### 説明

public function 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::newImage

(PECL imagick 2, PECL imagick 3)

Imagick::newImage — 新しい画像を作成する

### 説明

public function 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::newPseudoImage

(PECL imagick 2, PECL imagick 3)

Imagick::newPseudoImage — 新しい画像を作成する

### 説明

public function 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::nextImage

(PECL imagick 2, PECL imagick 3)

Imagick::nextImage — 次の画像に移動する

### 説明

public function Imagick::nextImage(): bool

画像リスト内の次の画像を Imagick オブジェクトに関連付けます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を返します。

# Imagick::normalizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::normalizeImage — カラー画像のコントラストを強調する

### 説明

public function 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::oilPaintImage

(PECL imagick 2, PECL imagick 3)

Imagick::oilPaintImage — 油絵をシミュレートする

### 説明

public function 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::opaquePaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::opaquePaintImage — 対象にマッチする任意のピクセルの色を変更する

### 説明

public function 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::optimizeImageLayers

(PECL imagick 2, PECL imagick 3)

Imagick::optimizeImageLayers — 画像の繰り返し部分を削除して最適化する

### 説明

public function 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::orderedPosterizeImage

(PECL imagick 2 >= 2.2.2, PECL imagick 3)

Imagick::orderedPosterizeImage — 配列ディザリングを行う

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function 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::paintFloodfillImage

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::paintFloodfillImage — 色にマッチするピクセルを変更する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function 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::paintOpaqueImage

(PECL imagick 2, PECL imagick 3)

Imagick::paintOpaqueImage — 色にマッチするピクセルを変更する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function 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::paintTransparentImage

(PECL imagick 2, PECL imagick 3)

Imagick::paintTransparentImage — 色にマッチするピクセルを塗りつぶし色に変更する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function 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::pingImage

(PECL imagick 2, PECL imagick 3)

Imagick::pingImage — 画像の基本属性を取得する

### 説明

public function Imagick::pingImage(string `$filename`): bool

このメソッドを使用すると、画像全体を読み込まなくても 画像の幅や高さ、サイズそしてフォーマットを取得できます。

### パラメータ

`filename`

  情報を読み込むファイル名。

### 戻り値

成功した場合に `true` を返します。

# Imagick::pingImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::pingImageBlob — 手早く属性を取得する

### 説明

public function 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::pingImageFile

(PECL imagick 2, PECL imagick 3)

Imagick::pingImageFile — 画像の基本属性を手軽に取得する

### 説明

public function 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::polaroidImage

(PECL imagick 2, PECL imagick 3)

Imagick::polaroidImage — ポラロイド写真をシミュレートする

### 説明

public function 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::posterizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::posterizeImage — 指定した色数まで画像を減色する

### 説明

public function 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::previewImages

(PECL imagick 2, PECL imagick 3)

Imagick::previewImages — 画像処理用の適切なパラメータを手早く取得する

### 説明

public function Imagick::previewImages(int `$preview`): bool

指定した画像の 9 枚のサムネイルをタイル状に並べ、 さまざまな強度で画像処理を適用します。 これは、画像処理操作のパラメータの適切な値を手早く知りたい場合に便利です。

### パラメータ

`preview`

  プレビュー形式。プレビュー形式の定数 を参照ください。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::previousImage

(PECL imagick 2, PECL imagick 3)

Imagick::previousImage — オブジェクト内の前の画像に移動する

### 説明

public function Imagick::previousImage(): bool

画像リスト内の前の画像を Imagick オブジェクトに関連付けます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を返します。

# Imagick::profileImage

(PECL imagick 2, PECL imagick 3)

Imagick::profileImage — 画像のプロファイルを追加あるいは削除する

### 説明

public function Imagick::profileImage(string `$name`, string `$profile` = ?): bool

ICC, IPTC, あるいは汎用のプロファイルを画像に追加あるいは削除します。 `profile` が `null` の場合は 画像からプロファイルを削除し、それ以外の場合は追加します。

画像からすべてのプロファイルを削除するには、 `name` に `'*'` を指定するか、 `profile` に `null` を指定します。

### パラメータ

`name`
  プロファイルの名前
`profile`
  プロファイルデータ。 `null` を設定すると、指定されたプロファイルが削除されます。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::quantizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::quantizeImage — 参照画像内の色を解析する

### 説明

public function 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::quantizeImages

(PECL imagick 2, PECL imagick 3)

Imagick::quantizeImages — 画像シーケンス内の色を解析する

### 説明

public function Imagick::quantizeImages(
int `$numberColors`,
int `$colorspace`,
int `$treedepth`,
bool `$dither`,
bool `$measureError`
): bool

### パラメータ

`numberColors`

`colorspace`

`treedepth`

`dither`

`measureError`

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::queryFontMetrics

(PECL imagick 2, PECL imagick 3)

Imagick::queryFontMetrics — フォントメトリクスを表す配列を返す

### 説明

public function 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::queryFonts

(PECL imagick 2, PECL imagick 3)

Imagick::queryFonts — 設定したフォントを返す

### 説明

public static function 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::queryFormats

(PECL imagick 2, PECL imagick 3)

Imagick::queryFormats — Imagick がサポートするフォーマットを返す

### 説明

public static function 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::radialBlurImage

(PECL imagick 2, PECL imagick 3)

Imagick::radialBlurImage — 画像にラジアルブラーを施す

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function 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::raiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::raiseImage — 三次元のボタン風の効果をシミュレートする

### 説明

public function 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();
    }

    ?>

# Imagick::randomThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::randomThresholdImage — コントラストの高い 2 色の画像を作成する

### 説明

public function 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::readImage

(PECL imagick 2, PECL imagick 3)

Imagick::readImage — ファイルから画像を読み込む

### 説明

public function Imagick::readImage(string `$filename`): bool

ファイルから画像を読み込みます。

### パラメータ

`filename`

### 戻り値

成功した場合に `true` を返します。

# Imagick::readImageBlob

(PECL imagick 2, PECL imagick 3)

Imagick::readImageBlob — バイナリ文字列から画像を読み込む

### 説明

public function 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::readImageFile

(PECL imagick 2, PECL imagick 3)

Imagick::readImageFile — オープンしているファイルハンドルから画像を読み込む

### 説明

public function Imagick::readImageFile(resource `$filehandle`, string `$fileName` = `null`): bool

オープンしているファイルハンドルから画像を読み込みます。

### パラメータ

`filehandle`

`fileName`

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::readimages

(PECL imagick 2, PECL imagick 3)

Imagick::readimages — ファイル名の配列から画像を読み込む

### 説明

public function Imagick::readImages(array `$filenames`): bool

ファイル名の配列から画像を読み込みます。 すべての画像は単一の Imagick オブジェクトに保持されます。

### パラメータ

`filenames`

### 戻り値

成功した場合に `true` を返します。

# Imagick::recolorImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::recolorImage — 画像の色を変更する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function 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::reduceNoiseImage

(PECL imagick 2, PECL imagick 3)

Imagick::reduceNoiseImage — 画像の輪郭をなめらかにする

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function 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::remapImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::remapImage — 画像の色を再配置する

### 説明

public function Imagick::remapImage(Imagick `$replacement`, int `$DITHER`): bool

画像の色を、`replacement` で定義したものに置き換えます。 色の変換は、もっとも近い色で行われます。このメソッドは、ImageMagick バージョン 6.4.5 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

`replacement`

  置き換える色を含む Imagick オブジェクト。

`DITHER`

  ディザメソッド定数 の一覧を参照ください。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::removeImage

(PECL imagick 2, PECL imagick 3)

Imagick::removeImage — 画像リストから画像を削除する

### 説明

public function Imagick::removeImage(): bool

画像リストから画像を削除します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::removeImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::removeImageProfile — 指定した名前の画像プロファイルを削除してそれを返す

### 説明

public function Imagick::removeImageProfile(string `$name`): string

指定した名前の画像プロファイルを削除してそれを返します。

### パラメータ

`name`

### 戻り値

画像のプロファイル名を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::render

(PECL imagick 2, PECL imagick 3)

Imagick::render — それまでのすべての描画コマンドをレンダリングする

### 説明

public function Imagick::render(): bool

それまでのすべての描画コマンドをレンダリングします。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を返します。

# Imagick::resampleImage

(PECL imagick 2, PECL imagick 3)

Imagick::resampleImage — 画像を指定した解像度にリサンプリングする

### 説明

public function 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::resetImagePage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::resetImagePage — 画像のページをリセットする

### 説明

public function Imagick::resetImagePage(string `$page`): bool

ページの定義は文字列で、書式は WxH+x+y となります。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

`page`

  ページ定義。たとえば `7168x5147+0+0` のようになります。

### 戻り値

成功した場合に `true` を返します。

# Imagick::resizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::resizeImage — 画像のサイズを変更する

### 説明

public function 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::rollImage

(PECL imagick 2, PECL imagick 3)

Imagick::rollImage — 画像を補正する

### 説明

public function 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::rotateImage

(PECL imagick 2, PECL imagick 3)

Imagick::rotateImage — 画像を回転する

### 説明

public function 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();
    }

    ?>

# Imagick::rotationalBlurImage

(PECL imagick 3 >= 3.3.0)

Imagick::rotationalBlurImage — 画像に回転ブラーを施す

### 説明

public function Imagick::rotationalBlurImage(float `$angle`, int `$channel` = Imagick::CHANNEL_DEFAULT): bool

画像に回転ブラーを施します。

### パラメータ

`angle`

  ブラーを適用する角度。

`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::roundCorners

(PECL imagick 2, PECL imagick 3)

Imagick::roundCorners — 画像の角を丸める

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function 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::sampleImage

(PECL imagick 2, PECL imagick 3)

Imagick::sampleImage — ピクセルのサンプリングによって画像の倍率を変更する

### 説明

public function Imagick::sampleImage(int `$columns`, int `$rows`): bool

ピクセルのサンプリングによって、指定した大きさに画像の倍率を変更します。 他の拡大・縮小メソッドとは異なり、 このメソッドは変更後の画像に新たな色を追加したりしません。

### パラメータ

`columns`

`rows`

### 戻り値

成功した場合に `true` を返します。

# Imagick::scaleImage

(PECL imagick 2, PECL imagick 3)

Imagick::scaleImage — 画像のサイズを変更する

### 説明

public function 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::segmentImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::segmentImage — 画像を分割する

### 説明

public function 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);

    ?>

# Imagick::selectiveBlurImage

(PECL imagick 3 >= 3.3.0)

Imagick::selectiveBlurImage — コントラストの閾値内で選択的に画像をぼかす

### 説明

public function Imagick::selectiveBlurImage(
float `$radius`,
float `$sigma`,
float `$threshold`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

コントラストの閾値内で選択的に画像をぼかします。一定の閾値を超えたコントラストのすべてをシャープにするアンシャープマスクに似ています。

### パラメータ

`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::separateImageChannel

(PECL imagick 2, PECL imagick 3)

Imagick::separateImageChannel — 画像からチャネルを分離する

### 説明

public function 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::sepiaToneImage

(PECL imagick 2, PECL imagick 3)

Imagick::sepiaToneImage — 画像をセピア調にする

### 説明

public function 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::setBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::setBackgroundColor — オブジェクトのデフォルト背景色を設定する

### 説明

public function Imagick::setBackgroundColor(mixed `$background`): bool

オブジェクトのデフォルト背景色を設定します。

### パラメータ

`background`

### 戻り値

成功した場合に `true` を返します。

### 変更履歴

バージョン | 説明
--- | ---
PECL imagick 2.1.0 | 色を表す文字列をパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

# Imagick::setColorspace

(PECL imagick 3)

Imagick::setColorspace — 色空間を設定する

### 説明

public function Imagick::setColorspace(int `$COLORSPACE`): bool

オブジェクトのグローバル色空間の値を設定します。 このメソッドは、ImageMagick バージョン 6.5.7 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

`COLORSPACE`

  COLORSPACE 定数 のひとつ。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::setCompression

(PECL imagick 2, PECL imagick 3)

Imagick::setCompression — オブジェクトのデフォルトの圧縮方式を設定する

### 説明

public function Imagick::setCompression(int `$compression`): bool

オブジェクトのデフォルトの圧縮方式を設定します。

### パラメータ

`compression`

  圧縮方式。Imagick::COMPRESSION_* 定数を参照ください。

### 戻り値

成功した場合に `true` を返します。

# Imagick::setCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::setCompressionQuality — オブジェクトのデフォルトの圧縮品質を設定する

### 説明

public function 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::setFilename

(PECL imagick 2, PECL imagick 3)

Imagick::setFilename — 画像を読み書きする前にファイル名を設定する

### 説明

public function Imagick::setFilename(string `$filename`): bool

画像を読み書きする前にファイル名を設定します。

### パラメータ

`filename`

### 戻り値

成功した場合に `true` を返します。

# Imagick::setFirstIterator

(PECL imagick 2, PECL imagick 3)

Imagick::setFirstIterator — Imagick イテレータを最初の画像に設定する

### 説明

public function Imagick::setFirstIterator(): bool

Imagick イテレータを最初の画像に設定します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を返します。

# Imagick::setFont

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setFont — フォントを設定する

### 説明

public function 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::setFormat

(PECL imagick 2, PECL imagick 3)

Imagick::setFormat — Imagick オブジェクトのフォーマットを設定する

### 説明

public function Imagick::setFormat(string `$format`): bool

Imagick オブジェクトのフォーマットを設定します。

### パラメータ

`format`

### 戻り値

成功した場合に `true` を返します。

# Imagick::setGravity

(PECL imagick 2 >= 2.2.0, PECL imagick 3)

Imagick::setGravity — gravity を設定する

### 説明

public function Imagick::setGravity(int `$gravity`): bool

Imagick オブジェクトのグローバル gravity プロパティを設定します。 このメソッドは、ImageMagick バージョン 6.4.0 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

`gravity`

  gravity プロパティ。 gravity 定数 の一覧を参照ください。

### 戻り値

値を返しません。

# Imagick::setImage

(PECL imagick 2, PECL imagick 3)

Imagick::setImage — オブジェクト内の画像を置き換える

### 説明

public function 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::setImageAlphaChannel

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setImageAlphaChannel — 画像のアルファチャネルを設定する

### 説明

public function Imagick::setImageAlphaChannel(int `$mode`): bool

画像のアルファチャネルを有効あるいは無効にします。`mode` には `Imagick::ALPHACHANNEL_*` 定数のいずれかを設定します。 このメソッドは、ImageMagick バージョン 6.3.8 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

`mode`

  `Imagick::ALPHACHANNEL_*` 定数のいずれか。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

### 参考

- Imagick::setImageMatte() - 画像のマットチャネルを設定する
- Imagick Alpha Channel 定数

# Imagick::setImageArtifact

(PECL imagick 3)

Imagick::setImageArtifact — 画像のアーチファクトを設定する

### 説明

public function 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() - 画像のアーチファクトを削除する

# Imagick::setImageAttribute

(PECL imagick 2, PECL imagick 3)

Imagick::setImageAttribute — 画像の属性を設定する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function Imagick::setImageAttribute(string `$key`, string `$value`): bool

画像の属性を設定します。

### パラメータ

`key`

`value`

### 戻り値

成功した場合に `true` を返します。

# Imagick::setImageBackgroundColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBackgroundColor — 画像の背景色を設定する

### 説明

public function Imagick::setImageBackgroundColor(mixed `$background`): bool

画像の背景色を設定します。

### パラメータ

`background`

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

### 変更履歴

バージョン | 説明
--- | ---
PECL imagick 2.1.0 | 色を表す文字列をパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

# Imagick::setImageBias

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBias — 画像を折りたたむ任意のメソッドについて画像のバイアスを設定する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function 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();
    }

    ?>

# Imagick::setImageBiasQuantum

(PECL imagick 3 >= 3.3.0)

Imagick::setImageBiasQuantum — 画像のバイアスを設定する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function Imagick::setImageBiasQuantum(float `$bias`): void

画像のバイアスを設定します。バイアスは `0` (調整なし) から `1` (quantum value) の範囲でスケーリングする必要があります。

### パラメータ

`bias`

### 戻り値

# Imagick::setImageBluePrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBluePrimary — 青が一番強い点を設定する

### 説明

public function Imagick::setImageBluePrimary(float `$x`, float `$y`): bool

青が一番強い点を設定します。

### パラメータ

`x`

`y`

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::setImageBorderColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageBorderColor — 画像の前景色を設定する

### 説明

public function Imagick::setImageBorderColor(mixed `$border`): bool

画像の前景色を設定します。

### パラメータ

`border`

  前景色。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

### 変更履歴

バージョン | 説明
--- | ---
PECL imagick 2.1.0 | 色を表す文字列をパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

# Imagick::setImageChannelDepth

(PECL imagick 2, PECL imagick 3)

Imagick::setImageChannelDepth — 特定の画像チャネルの深度を設定する

### 説明

public function Imagick::setImageChannelDepth(int `$channel`, int `$depth`): bool

特定の画像チャネルの深度を設定します。

### パラメータ

`channel`

`depth`

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::setImageClipMask

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::setImageClipMask — 画像のクリップマスクを設定する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function 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::setImageColormapColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageColormapColor — 指定した色マップインデックスの色を設定する

### 説明

public function Imagick::setImageColormapColor(int `$index`, ImagickPixel `$color`): bool

指定した色マップインデックスの色を設定します。

### パラメータ

`index`

`color`

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::setImageColorspace

(PECL imagick 2, PECL imagick 3)

Imagick::setImageColorspace — 画像の色空間を設定する

### 説明

public function Imagick::setImageColorspace(int `$colorspace`): bool

画像の色空間を設定します。 このメソッドは、新しい画像を作るときに使うものです。 既存の画像の色空間を変更したい場合は、Imagick::transformImageColorspace() を使う必要があります。

### パラメータ

`colorspace`

  COLORSPACE 定数のいずれか。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::setImageCompose

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompose — 画像の合成演算子を設定する

### 説明

public function Imagick::setImageCompose(int `$compose`): bool

画像の合成演算子を設定します。Imagick::montageImage() メソッドを使用して画像のサムネイルを作成する方法を指定する際に便利です。

### パラメータ

`compose`

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::setImageCompression

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompression — 画像の圧縮を設定する

### 説明

public function Imagick::setImageCompression(int `$compression`): bool

画像の圧縮を設定します。

### パラメータ

`compression`

  `COMPRESSION` 定数のいずれか。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::setImageCompressionQuality

(PECL imagick 2, PECL imagick 3)

Imagick::setImageCompressionQuality — 画像の圧縮品質を設定する

### 説明

public function 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::setImageDelay

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDelay — 画像の遅延を設定する

### 説明

public function 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::setImageDepth

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDepth — 画像の深度を設定する

### 説明

public function Imagick::setImageDepth(int `$depth`): bool

画像の深度を設定します。

### パラメータ

`depth`

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::setImageDispose

(PECL imagick 2, PECL imagick 3)

Imagick::setImageDispose — 画像の配置方法を設定する

### 説明

public function Imagick::setImageDispose(int `$dispose`): bool

画像の配置方法を設定します。

### パラメータ

`dispose`

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::setImageExtent

(PECL imagick 2, PECL imagick 3)

Imagick::setImageExtent — 画像のサイズを設定する

### 説明

public function Imagick::setImageExtent(int `$columns`, int `$rows`): bool

画像のサイズ (つまりカラム数と行数) を設定します。

### パラメータ

`columns`

`rows`

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::setImageFilename

(PECL imagick 2, PECL imagick 3)

Imagick::setImageFilename — 特定の画像のファイル名を設定する

### 説明

public function Imagick::setImageFilename(string `$filename`): bool

シーケンス内の特定の画像のファイル名を設定します。

### パラメータ

`filename`

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::setImageFormat

(PECL imagick 2, PECL imagick 3)

Imagick::setImageFormat — 特定の画像のフォーマットを設定する

### 説明

public function Imagick::setImageFormat(string `$format`): bool

シーケンス内の特定の画像のフォーマットを設定します。

### パラメータ

`format`

  画像フォーマットを表す文字列。対応するフォーマットは、 インストールされている ImageMagick に依存します。

### 戻り値

成功した場合に `true` を返します。

# Imagick::setImageGamma

(PECL imagick 2, PECL imagick 3)

Imagick::setImageGamma — 画像のガンマを設定する

### 説明

public function Imagick::setImageGamma(float `$gamma`): bool

画像のガンマを設定します。

### パラメータ

`gamma`

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::setImageGravity

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::setImageGravity — 画像の gravity を設定する

### 説明

public function Imagick::setImageGravity(int `$gravity`): bool

原罪の画像の gravity プロパティを設定します。 このメソッドを使うと、単一の画像シーケンスの gravity プロパティを設定することができます。 このメソッドは、ImageMagick バージョン 6.4.4 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

`gravity`

  gravity プロパティ。 gravity 定数 の一覧を参照ください。

### 戻り値

値を返しません。

# Imagick::setImageGreenPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageGreenPrimary — 緑が一番強い点を設定する

### 説明

public function Imagick::setImageGreenPrimary(float `$x`, float `$y`): bool

緑が一番強い点を設定します。

### パラメータ

`x`

`y`

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::setImageIndex

(PECL imagick 2, PECL imagick 3)

Imagick::setImageIndex — イテレータの位置を設定する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function Imagick::setImageIndex(int `$index`): bool

画像リスト内でのイテレータの位置、index パラメータで指定した場所に設定します。

このメソッドは非推奨です。 Imagick::setIteratorIndex() を参照ください。

### パラメータ

`index`

  イテレータを設定する位置。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::setImageInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::setImageInterlaceScheme — 画像のインターレース手法を設定する

### 説明

public function Imagick::setImageInterlaceScheme(int `$interlace_scheme`): bool

画像の圧縮を設定します。

### パラメータ

`interlace_scheme`

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::setImageInterpolateMethod

(PECL imagick 2, PECL imagick 3)

Imagick::setImageInterpolateMethod — 画像のピクセル補間方式を設定する

### 説明

public function Imagick::setImageInterpolateMethod(int `$method`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

画像のピクセル補間方式を設定します。

### パラメータ

`method`

  `Imagick::INTERPOLATE_*` 定数のいずれか。

### 戻り値

成功した場合に `true` を返します。

# Imagick::setImageIterations

(PECL imagick 2, PECL imagick 3)

Imagick::setImageIterations — 画像の反復を設定する

### 説明

public function 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::setImageMatte

(PECL imagick 2, PECL imagick 3)

Imagick::setImageMatte — 画像のマットチャネルを設定する

### 説明

public function Imagick::setImageMatte(bool `$matte`): bool

画像のマットチャネルを設定します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

`matte`

  True にするとマットチャネルを有効にし、false の場合は無効にします。

### 戻り値

成功した場合に `true` を返します。

# Imagick::setImageMatteColor

(PECL imagick 2, PECL imagick 3)

Imagick::setImageMatteColor — 画像のマット色を設定する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function Imagick::setImageMatteColor(mixed `$matte`): bool

画像のマット色を設定します。

### パラメータ

`matte`

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

### 変更履歴

バージョン | 説明
--- | ---
PECL imagick 2.1.0 | 色を表す文字列をパラメータとして指定できるようになりました。 これまでのバージョンでは ImagickPixel オブジェクトしか指定できませんでした。

# Imagick::setImageOpacity

(PECL imagick 2, PECL imagick 3)

Imagick::setImageOpacity — 画像の不透明度を設定する

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function 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::setImageOrientation

(PECL imagick 2, PECL imagick 3)

Imagick::setImageOrientation — 画像の方向を設定する

### 説明

public function 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::setImagePage

(PECL imagick 2, PECL imagick 3)

Imagick::setImagePage — 画像のページのジオメトリを設定する

### 説明

public function Imagick::setImagePage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

画像のページのジオメトリを設定します。

### パラメータ

`width`

`height`

`x`

`y`

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::setImageProfile

(PECL imagick 2, PECL imagick 3)

Imagick::setImageProfile — 指定した名前の画像プロファイルを Imagick オブジェクトに追加する

### 説明

public function Imagick::setImageProfile(string `$name`, string `$profile`): bool

指定した名前の画像プロファイルを Imagick オブジェクトに追加します。 同じ名前のプロファイルが存在する場合は、それを置き換えます。 このメソッドは Imagick::ProfileImage() メソッドとは異なり、 CMS カラープロファイルは適用しません。

### パラメータ

`name`

`profile`

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::setImageProperty

(PECL imagick 2, PECL imagick 3)

Imagick::setImageProperty — 画像のプロパティを設定する

### 説明

public function 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::setImageRedPrimary

(PECL imagick 2, PECL imagick 3)

Imagick::setImageRedPrimary — 赤が一番強い点を設定する

### 説明

public function Imagick::setImageRedPrimary(float `$x`, float `$y`): bool

赤が一番強い点を設定します。

### パラメータ

`x`

`y`

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::setImageRenderingIntent

(PECL imagick 2, PECL imagick 3)

Imagick::setImageRenderingIntent — 画像のレンダリング方向を設定する

### 説明

public function Imagick::setImageRenderingIntent(int `$rendering_intent`): bool

画像のレンダリング方向を設定します。

### パラメータ

`rendering_intent`

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::setImageResolution

(PECL imagick 2, PECL imagick 3)

Imagick::setImageResolution — 画像の解像度を設定する

### 説明

public function 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::setImageScene

(PECL imagick 2, PECL imagick 3)

Imagick::setImageScene — 画像のシーンを設定する

### 説明

public function Imagick::setImageScene(int `$scene`): bool

画像のシーンを設定します。

### パラメータ

`scene`

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::setImageTicksPerSecond

(PECL imagick 2, PECL imagick 3)

Imagick::setImageTicksPerSecond — 画像の ticks-per-second を設定する

### 説明

public function 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::setImageType

(PECL imagick 2, PECL imagick 3)

Imagick::setImageType — 画像の型を設定する

### 説明

public function Imagick::setImageType(int `$image_type`): bool

画像の型を設定します。

### パラメータ

`image_type`

### 戻り値

成功した場合に `true` を返します。

# Imagick::setImageUnits

(PECL imagick 2, PECL imagick 3)

Imagick::setImageUnits — 画像の解像度の単位を設定する

### 説明

public function Imagick::setImageUnits(int `$units`): bool

画像の解像度の単位を設定します。

### パラメータ

`units`

### 戻り値

成功した場合に `true` を返します。

# Imagick::setImageVirtualPixelMethod

(PECL imagick 2, PECL imagick 3)

Imagick::setImageVirtualPixelMethod — 画像の仮想ピクセルメソッドを設定する

### 説明

public function Imagick::setImageVirtualPixelMethod(int `$method`): bool

画像の仮想ピクセルメソッドを設定します。

### パラメータ

`method`

### 戻り値

成功した場合に `true` を返します。

# Imagick::setImageWhitePoint

(PECL imagick 2, PECL imagick 3)

Imagick::setImageWhitePoint — 画像の色度が白い点を設定する

### 説明

public function Imagick::setImageWhitePoint(float `$x`, float `$y`): bool

画像の色度が白い点を設定します。

### パラメータ

`x`

`y`

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::setInterlaceScheme

(PECL imagick 2, PECL imagick 3)

Imagick::setInterlaceScheme — 画像の圧縮を設定する

### 説明

public function Imagick::setInterlaceScheme(int `$interlace_scheme`): bool

画像の圧縮を設定します。

### パラメータ

`interlace_scheme`

### 戻り値

成功した場合に `true` を返します。

# Imagick::setIteratorIndex

(PECL imagick 2, PECL imagick 3)

Imagick::setIteratorIndex — イテレータの位置を設定する

### 説明

public function 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::setLastIterator

(PECL imagick 2 >= 2.0.1, PECL imagick 3)

Imagick::setLastIterator — Imagick イテレータを最後の画像に設定する

### 説明

public function Imagick::setLastIterator(): bool

Imagick イテレータを最後の画像に設定します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を返します。

# Imagick::setOption

(PECL imagick 2, PECL imagick 3)

Imagick::setOption — オプションを設定する

### 説明

public function 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::setPage

(PECL imagick 2, PECL imagick 3)

Imagick::setPage — Imagick オブジェクトのページジオメトリを設定する

### 説明

public function Imagick::setPage(
int `$width`,
int `$height`,
int `$x`,
int `$y`
): bool

Imagick オブジェクトのページジオメトリを設定します。

### パラメータ

`width`

`height`

`x`

`y`

### 戻り値

成功した場合に `true` を返します。

# Imagick::setPointSize

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

Imagick::setPointSize — ポイントサイズを設定する

### 説明

public function 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() - ポイントサイズを取得する

# Imagick::setProgressMonitor

(PECL imagick 3 >= 3.3.0)

Imagick::setProgressMonitor — 処理中に呼び出されるコールバックを設定する

### 説明

public function Imagick::setProgressMonitor(callable `$callback`): bool

Imagick 画像の処理中に呼び出されるコールバックを設定します。

### パラメータ

`callback`

  呼び出す進捗関数。画像処理を続行する場合は true を、キャンセルする場合は false を返す必要があります。offset パラメータは進捗状況を示し、span パラメータは必要な作業の総量を示します。

  function callback ( mixed `$offset` , mixed `$span` ): bool
  警告

  コールバック関数に渡される値は一定ではありません。特に span パラメータは画像処理中に増加することがあります。このため、画像操作の完了率を計算することは単純ではありません。

### 戻り値

成功した場合に `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);
                }
            }

    ?>

# Imagick::setRegistry

(PECL imagick 3 >= 3.3.0)

Imagick::setRegistry — 指定されたキーの ImageMagick レジストリエントリに値を設定する

### 説明

public static function Imagick::setRegistry(string `$key`, string `$value`): bool

指定されたキーの ImageMagick レジストリエントリに値を設定します。 これは主に "temporary-path" の設定に役立ちます。 "temporary-path" は、たとえば PDF の処理中に ImageMagick が 一時的な画像を作成する場所を制御します。

### パラメータ

`key`

`value`

### 戻り値

成功した場合に `true` を返します。

# Imagick::setResolution

(PECL imagick 2, PECL imagick 3)

Imagick::setResolution — 画像の解像度を設定する

### 説明

public function Imagick::setResolution(float `$x_resolution`, float `$y_resolution`): bool

画像の解像度を設定します。

### パラメータ

`x_resolution`

  水平方向の解像度。

`y_resolution`

  垂直方向の解像度。

### 戻り値

成功した場合に `true` を返します。

### 注意

Imagick::setResolution() は、画像の読み込みや作成の前に呼ぶ必要があります。

### 参考

- Imagick::setImageResolution() - 画像の解像度を設定する
- Imagick::getImageResolution() - 画像の X 方向と Y 方向の解像度を取得する

# Imagick::setResourceLimit

(PECL imagick 2, PECL imagick 3)

Imagick::setResourceLimit — 特定のリソースの制限を設定する

### 説明

public static function Imagick::setResourceLimit(int `$type`, int `$limit`): bool

このメソッドを使って、ImageMagick ライブラリのリソース制限を変更します。

### パラメータ

`type`

  リソースタイプ定数 のうちのひとつ。

`limit`

  リソースの制限。単位は、制限するリソースの種類によって異なります。

### 戻り値

成功した場合に `true` を返します。

### 参考

- Imagick::getResourceLimit() - 指定したリソースの制限を返す

# Imagick::setSamplingFactors

(PECL imagick 2, PECL imagick 3)

Imagick::setSamplingFactors — 画像のサンプリング係数を設定する

### 説明

public function 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::setSize

(PECL imagick 2, PECL imagick 3)

Imagick::setSize — Imagick オブジェクトのサイズを設定する

### 説明

public function Imagick::setSize(int `$columns`, int `$rows`): bool

Imagick オブジェクトのサイズを設定します。 RGB や GRAY、CMYK といった生の画像フォーマットを読み込む前に設定します。

### パラメータ

`columns`

`rows`

### 戻り値

成功した場合に `true` を返します。

# Imagick::setSizeOffset

(PECL imagick 2, PECL imagick 3)

Imagick::setSizeOffset — Imagick オブジェクトのサイズのオフセットを設定する

### 説明

public function Imagick::setSizeOffset(int `$columns`, int `$rows`, int `$offset`): bool

Imagick オブジェクトのサイズとオフセットを設定します。 RGB や GRAY、CMYK といった生の画像フォーマットを読み込む前に設定します。 このメソッドは、ImageMagick バージョン 6.2.9 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

`columns`

  幅 (ピクセル単位)。

`rows`

  高さ (ピクセル単位)。

`offset`

  画像のオフセット。

### 戻り値

成功した場合に `true` を返します。

# Imagick::setType

(PECL imagick 2, PECL imagick 3)

Imagick::setType — 画像タイプ属性を設定する

### 説明

public function Imagick::setType(int `$image_type`): bool

画像タイプ属性を設定します。

### パラメータ

`image_type`

### 戻り値

成功した場合に `true` を返します。

# Imagick::shadeImage

(PECL imagick 2, PECL imagick 3)

Imagick::shadeImage — 3D 効果を作成する

### 説明

public function 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::shadowImage

(PECL imagick 2, PECL imagick 3)

Imagick::shadowImage — 画像の影をシミュレートする

### 説明

public function 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::sharpenImage

(PECL imagick 2, PECL imagick 3)

Imagick::sharpenImage — 画像をシャープにする

### 説明

public function 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::shaveImage

(PECL imagick 2, PECL imagick 3)

Imagick::shaveImage — 画像の輪郭からピクセルを刈り取る

### 説明

public function 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::shearImage

(PECL imagick 2, PECL imagick 3)

Imagick::shearImage — 平行四辺形を作成する

### 説明

public function 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::sigmoidalContrastImage

(PECL imagick 2, PECL imagick 3)

Imagick::sigmoidalContrastImage — 画像のコントラストを調整する

### 説明

public function 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::sketchImage

(PECL imagick 2, PECL imagick 3)

Imagick::sketchImage — 鉛筆画をシミュレートする

### 説明

public function 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();
    }

    ?>

# Imagick::smushImages

(PECL imagick 3 >= 3.3.0)

Imagick::smushImages — 現在の画像ポインタから画像リストの最後までのすべての画像を取得し、結合する

### 説明

public function Imagick::smushImages(bool `$stack`, int `$offset`): Imagick

現在の画像ポインタから画像リストの最後までのすべての画像を取得し、 stack パラメータが true の場合は上から下に、それ以外の場合は左から右に結合します。

### パラメータ

`stack`

`offset`

### 戻り値

結合された新しい画像を返します。

### 例

例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::solarizeImage

(PECL imagick 2, PECL imagick 3)

Imagick::solarizeImage — 画像にソラリゼーション効果を適用する

### 説明

public function 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::sparseColorImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::sparseColorImage — 色を補間する

### 説明

public function 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::spliceImage

(PECL imagick 2, PECL imagick 3)

Imagick::spliceImage — 無地の画像を作成する

### 説明

public function 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::spreadImage

(PECL imagick 2, PECL imagick 3)

Imagick::spreadImage — ブロック内の各ピクセルをランダムに移動する

### 説明

public function 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();
    }

    ?>

# Imagick::statisticImage

(PECL imagick 3 >= 3.3.0)

Imagick::statisticImage — 統計関数を使用して画像を変更する

### 説明

public function Imagick::statisticImage(
int `$type`,
int `$width`,
int `$height`,
int `$channel` = Imagick::CHANNEL_DEFAULT
): bool

各ピクセルを、指定した幅と高さの近傍ピクセルの統計値で置き換えます。

### パラメータ

`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::steganoImage

(PECL imagick 2, PECL imagick 3)

Imagick::steganoImage — デジタル透かしを画像に埋め込む

### 説明

public function Imagick::steganoImage(Imagick `$watermark_wand`, int `$offset`): Imagick

デジタル透かしを画像に埋め込みます。 あとでこの透かしが見つかれば、その画像の出所を証明することができます。 offset は、透かしの埋め込みを開始する位置を指定します。

### パラメータ

`watermark_wand`

`offset`

### 戻り値

成功した場合に `true` を返します。

# Imagick::stereoImage

(PECL imagick 2, PECL imagick 3)

Imagick::stereoImage — ふたつの画像を合成する

### 説明

public function Imagick::stereoImage(Imagick `$offset_wand`): bool

ふたつの画像を合成してひとつの画像にします。 左と右の画像を合成してステレオ効果を生み出します。

### パラメータ

`offset_wand`

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::stripImage

(PECL imagick 2, PECL imagick 3)

Imagick::stripImage — 画像からすべてのプロパティやコメントを除去する

### 説明

public function Imagick::stripImage(): bool

画像からすべてのプロパティやコメントを除去します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を返します。

### エラー / 例外

エラー時に ImagickException をスローします。

# Imagick::subImageMatch

(PECL imagick 3 >= 3.3.0)

Imagick::subImageMatch — 現在の画像から部分画像を検索し、類似度画像を返す

### 説明

public function Imagick::subImageMatch(Imagick `$Imagick`, array `&$offset` = ?, float `&$similarity` = ?): Imagick

現在の画像から部分画像を検索し、類似度画像を返します。 完全に一致する箇所は白、まったく一致しない箇所は黒、 その中間はグレーの階調で表現されます。 オプションのパラメータ bestMatch と similarity を渡すこともできます。 この関数の呼び出し後、similarity には部分画像と元画像中の一致箇所との 類似度の「スコア」が設定されます。bestMatch には一致した領域を示す x, y, width, height の要素を持つ連想配列が格納されます。

### パラメータ

`Imagick`

`offset`

`similarity`

  各ピクセルの類似度を表す新しい画像。

### 戻り値

### 例

例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::swirlImage

(PECL imagick 2, PECL imagick 3)

Imagick::swirlImage — 画像の中心から、ピクセルを渦巻状にする

### 説明

function 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::textureImage

(PECL imagick 2, PECL imagick 3)

Imagick::textureImage — テクスチャ画像をタイル状に並べる

### 説明

function 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::thresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::thresholdImage — 閾値にもとづいて個々のピクセルの値を変更する

### 説明

public function 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::thumbnailImage

(PECL imagick 2, PECL imagick 3)

Imagick::thumbnailImage — 画像のサイズを変更する

### 説明

public function 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`

  最大値を強制的に使用するかどうか。

`fill`

  画像がボックスを完全に埋め尽くさない場合、 ボックスは背景色で塗りつぶされます。

`legacy`

  次元を一番近い整数に丸めるのではなく、小さくなる方向に丸めます。

### 戻り値

成功した場合に `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::tintImage

(PECL imagick 2, PECL imagick 3)

Imagick::tintImage — 色ベクトルを画像の各ピクセルに適用する

### 説明

public function 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();
    }

    ?>

# Imagick::__toString

(PECL imagick 2, PECL imagick 3)

Imagick::__toString — 画像を文字列として返す

### 説明

public function Imagick::__toString(): string

現在の画像を文字列として返します。返される画像は一枚だけです。複数の画像を含む Imagick オブジェクト（アニメーション GIF や複数ページの PDF など）に対しては使うべきではありません。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合は文字列の内容を、失敗した場合は空文字列を返します。

### 参考

- Imagick::getImageBlob() - 画像シーケンスを blob で返す
- Imagick::getImagesBlob() - すべての画像シーケンスを blob で返す

# Imagick::transformImage

(PECL imagick 2, PECL imagick 3)

Imagick::transformImage — 切り取るサイズと画像のジオメトリを設定する便利なメソッド

警告

この関数は Imagick 3.4.4 以降では 非推奨 になりました。この関数に依存したコードを書くのはやめましょう。

### 説明

public function 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() - 画像のサイズを変更する

# Imagick::transformImageColorspace

(PECL imagick 3)

Imagick::transformImageColorspace — 画像を新しい色空間に変換する

### 説明

public function Imagick::transformImageColorspace(int `$colorspace`): bool

画像を新しい色空間に変換します。

### パラメータ

`colorspace`

  画像の変換先の色空間。COLORSPACE 定数のいずれか (例: Imagick::COLORSPACE_CMYK)。

### 戻り値

成功した場合に `true` を返します。

### 例

例1 Imagick::transformImageColorspace() の例

画像を新しい色空間に変換し、個々のチャネル値を確認できるよう単一のチャネルを抽出します。

    <?php
    function transformImageColorspace($imagePath, $colorSpace, $channel) {
        $imagick = new \Imagick(realpath($imagePath));
        $imagick->transformimagecolorspace($colorSpace);
        //channel はチャネル定数のいずれか（例: \Imagick::CHANNEL_BLUE）
        $imagick->separateImageChannel($channel);
        header("Content-Type: image/jpg");
        echo $imagick->getImageBlob();
    }
    ?>

### 参考

- Imagick::setColorSpace() - 色空間を設定する

# Imagick::transparentPaintImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::transparentPaintImage — ピクセルを透過させる

### 説明

public function 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::transposeImage

(PECL imagick 2, PECL imagick 3)

Imagick::transposeImage — 垂直方向に反転させた画像を作成する

### 説明

public function 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::transverseImage

(PECL imagick 2, PECL imagick 3)

Imagick::transverseImage — 水平方向に反転させた画像を作成する

### 説明

public function 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::trimImage

(PECL imagick 2, PECL imagick 3)

Imagick::trimImage — 画像の輪郭を削除する

### 説明

public function 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() - 利用可能なモードを指定して、画像を自動的にクロップする

# Imagick::uniqueImageColors

(PECL imagick 2,PECL imagick 3)

Imagick::uniqueImageColors — ある 1 色以外のすべての色のピクセルを削除する

### 説明

public function 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::unsharpMaskImage

(PECL imagick 2, PECL imagick 3)

Imagick::unsharpMaskImage — 画像をシャープにする

### 説明

public function 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::valid

(PECL imagick 2, PECL imagick 3)

Imagick::valid — 現在のアイテムが有効かどうかを調べる

### 説明

public function Imagick::valid(): bool

現在のアイテムが有効かどうかを調べます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を返します。

# Imagick::vignetteImage

(PECL imagick 2, PECL imagick 3)

Imagick::vignetteImage — ビネットフィルタを画像に追加する

### 説明

public function 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::waveImage

(PECL imagick 2, PECL imagick 3)

Imagick::waveImage — ウェーブフィルタを画像に適用する

### 説明

public function 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::whiteThresholdImage

(PECL imagick 2, PECL imagick 3)

Imagick::whiteThresholdImage — 閾値に満たないすべてのピクセルを白にする

### 説明

public function 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::writeImage

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImage — 指定した名前で画像を書き込む

### 説明

public function Imagick::writeImage(string `$filename` = NULL): bool

指定した名前で画像を書き込みます。filename パラメータが NULL の場合は、 Imagick::readImage() あるいは Imagick::setImageFilename() で設定した名前で書き込みます。

### パラメータ

`filename`

  画像を書き出すファイル名。ファイルの拡張子で画像形式が決まります。 "jpg:test.png" のようにプレフィックスをつけると、拡張子が何であっても特定の形式で保存できます。

### 戻り値

成功した場合に `true` を返します。

# Imagick::writeImageFile

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImageFile — 画像をファイルハンドルに書き出す

### 説明

public function Imagick::writeImageFile(resource `$filehandle`, string `$format` = ?): bool

開いているファイルハンドルに画像シーケンスを書き出します。 ハンドルは、fopen などで開いておかなければなりません。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

`filehandle`

  画像を書き出すファイルハンドル。

`format`

  画像のフォーマット。 指定できる有効なフォーマットのリストは、 ImageMagick のコンパイル時に有効にした機能に依存します。 有効なフォーマットは、 Imagick::queryFormats() を使って実行時にも確認できます。

### 戻り値

成功した場合に `true` を返します。

### 参考

- Imagick::queryFormats() - Imagick がサポートするフォーマットを返す

# Imagick::writeImages

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImages — 画像あるいは画像シーケンスを書き込む

### 説明

public function Imagick::writeImages(string `$filename`, bool `$adjoin`): bool

画像あるいは画像シーケンスを書き込みます。

### パラメータ

`filename`

`adjoin`

### 戻り値

成功した場合に `true` を返します。

# Imagick::writeImagesFile

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

Imagick::writeImagesFile — フレームをファイルハンドルに書き出す

### 説明

public function Imagick::writeImagesFile(resource `$filehandle`, string `$format` = ?): bool

開いているファイルハンドルにすべての画像フレームを書き出します。 このメソッドを使うと、アニメーション gif やその他のマルチフレーム画像を書き出すことができます。 このメソッドは、ImageMagick バージョン 6.3.6 以降で Imagick をコンパイルした場合に使用可能です。

### パラメータ

`filehandle`

  画像を書き出すファイルハンドル。

`format`

  画像のフォーマット。 指定できる有効なフォーマットのリストは、 ImageMagick のコンパイル時に有効にした機能に依存します。 有効なフォーマットは、 Imagick::queryFormats() を使って実行時にも確認できます。

### 戻り値

成功した場合に `true` を返します。

### 参考

- Imagick::queryFormats() - 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 — 特定の画像チャネルのレベルを調整する
- Imagick::averageImages — 画像群を平均化する
- Imagick::blackThresholdImage — 閾値に満たないすべてのピクセルを黒にする
- Imagick::blueShiftImage — 画像の色を落ち着かせる
- Imagick::blurImage — blur (にじみ) フィルタを画像に追加する
- Imagick::borderImage — 画像の周りを枠線で囲む
- Imagick::brightnessContrastImage — 画像の明るさやコントラストを変更する
- Imagick::charcoalImage — 木炭画をシミュレートする
- Imagick::chopImage — 画像の一部を取り除き、切り詰める
- Imagick::clampImage — 色の範囲を 0 から quantum depth までに制限する
- Imagick::clear — Imagick オブジェクトに関連付けられたすべてのリソースをクリアする
- Imagick::clipImage — 8BIM プロファイルの最初のパスにそって切り取る
- Imagick::clipImagePath — 8BIM プロファイルの名前付きパスがあればそれに沿ってクリップする
- Imagick::clipPathImage — 8BIM プロファイルの指定した名前のパスにそって切り取る
- Imagick::clone — Imagick オブジェクトの完全なコピーを作成する
- Imagick::clutImage — 画像の色を置き換える
- Imagick::coalesceImages — 複数の画像を合成する
- Imagick::colorFloodfillImage — 対象にマッチする任意の点の色の値を変更する
- Imagick::colorizeImage — 塗りつぶし色と画像を混合する
- Imagick::colorMatrixImage — 画像に色変換を適用する
- Imagick::combineImages — ひとつあるいは複数の画像をひとつにまとめる
- Imagick::commentImage — コメントを画像に追加する
- Imagick::compareImageChannels — ひとつあるいは複数の画像の差を返す
- Imagick::compareImageLayers — 複数の画像の中で最大の境界範囲を返す
- Imagick::compareImages — ある画像を再構築された画像と比較する
- Imagick::compositeImage — ある画像を別の画像に合成する
- Imagick::__construct — Imagick のコンストラクタ
- Imagick::contrastImage — 画像のコントラストを変更する
- Imagick::contrastStretchImage — カラー画像のコントラストを強調する
- Imagick::convolveImage — 独自の畳み込み関数を画像に適用する
- Imagick::count — 画像の数を取得する
- Imagick::cropImage — 画像の一部を抽出する
- Imagick::cropThumbnailImage — 切り取ってサムネイルを作成する
- Imagick::current — 現在の Imagick オブジェクトへの参照を返す
- Imagick::cycleColormapImage — 画像のカラーマップを移動する
- Imagick::decipherImage — 画像を復号する
- Imagick::deconstructImages — 画像間の特定のピクセルの差を返す
- Imagick::deleteImageArtifact — 画像のアーチファクトを削除する
- Imagick::deleteImageProperty — 画像のプロパティを削除する
- 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 — カスタム畳み込みカーネルを画像に適用する
- Imagick::flattenImages — 画像シーケンスをマージする
- Imagick::flipImage — 垂直方向に反転した画像を作成する
- Imagick::floodFillPaintImage — 対象にマッチする任意のピクセルの値を変更する
- Imagick::flopImage — 水平方向に反転した画像を作成する
- Imagick::forwardFourierTransformImage — 離散フーリエ変換 (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 — 名前を指定して属性を返す
- 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 — 画像の MIME タイプを返す
- 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 — ImageMagick の quantum range を返す
- Imagick::getQuantumDepth — quantum depth を取得する
- Imagick::getQuantumRange — Imagick quantum range を返す
- Imagick::getRegistry — StringRegistry エントリを取得する
- Imagick::getReleaseDate — ImageMagick のリリース日を返す
- Imagick::getResource — 指定したリソースのメモリ使用状況を返す
- Imagick::getResourceLimit — 指定したリソースの制限を返す
- Imagick::getSamplingFactors — 水平方向および垂直方向のサンプリング係数を取得する
- Imagick::getSize — Imagick オブジェクトに関連付けられたサイズを返す
- Imagick::getSizeOffset — サイズのオフセットを返す
- Imagick::getVersion — ImageMagick API のバージョンを返す
- Imagick::haldClutImage — 画像内の色を置換する
- Imagick::hasNextImage — オブジェクトが次の画像を保持しているかどうかを調べる
- Imagick::hasPreviousImage — オブジェクトが前の画像を保持しているかどうかを調べる
- Imagick::identifyFormat — 画像の詳細情報で文字列をフォーマットする
- Imagick::identifyImage — 画像を識別し、属性を取得する
- Imagick::implodeImage — 新しい画像をコピーとして作成する
- Imagick::importImagePixels — 画像のピクセルをインポートする
- Imagick::inverseFourierTransformImage — 逆離散フーリエ変換 (DFT) を実行する
- Imagick::labelImage — ラベルを画像に追加する
- Imagick::levelImage — 画像のレベルを調節する
- Imagick::linearStretchImage — 画像の輝度を引き伸ばして飽和させる
- Imagick::liquidRescaleImage — 画像を動かす
- Imagick::listRegistry — すべてのレジストリ設定を一覧表示する
- Imagick::magnifyImage — 画像を 2 倍に比例拡大する
- Imagick::mapImage — 画像の色を、参照画像の中の最も近い色に置き換える
- Imagick::matteFloodfillImage — 色の透明度を変更する
- Imagick::medianFilterImage — デジタルフィルタを適用する
- Imagick::mergeImageLayers — 画像のレイヤーをマージする
- Imagick::minifyImage — 画像をその半分のサイズに比例縮小する
- Imagick::modulateImage — 明度、飽和度、色相を制御する
- Imagick::montageImage — 合成画像を作成する
- Imagick::morphImages — 複数の画像をモーフィングする
- Imagick::morphology — 指定されたモルフォロジーメソッドに従い、ユーザー指定のカーネルを画像に適用する
- 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 — ファイル名の配列から画像を読み込む
- Imagick::recolorImage — 画像の色を変更する
- Imagick::reduceNoiseImage — 画像の輪郭をなめらかにする
- Imagick::remapImage — 画像の色を再配置する
- Imagick::removeImage — 画像リストから画像を削除する
- Imagick::removeImageProfile — 指定した名前の画像プロファイルを削除してそれを返す
- Imagick::render — それまでのすべての描画コマンドをレンダリングする
- Imagick::resampleImage — 画像を指定した解像度にリサンプリングする
- Imagick::resetImagePage — 画像のページをリセットする
- Imagick::resizeImage — 画像のサイズを変更する
- Imagick::rollImage — 画像を補正する
- Imagick::rotateImage — 画像を回転する
- Imagick::rotationalBlurImage — 画像に回転ブラーを施す
- Imagick::roundCorners — 画像の角を丸める
- Imagick::sampleImage — ピクセルのサンプリングによって画像の倍率を変更する
- Imagick::scaleImage — 画像のサイズを変更する
- Imagick::segmentImage — 画像を分割する
- Imagick::selectiveBlurImage — コントラストの閾値内で選択的に画像をぼかす
- 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 — 画像の属性を設定する
- Imagick::setImageBackgroundColor — 画像の背景色を設定する
- Imagick::setImageBias — 画像を折りたたむ任意のメソッドについて画像のバイアスを設定する
- Imagick::setImageBiasQuantum — 画像のバイアスを設定する
- 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 — 処理中に呼び出されるコールバックを設定する
- Imagick::setRegistry — 指定されたキーの ImageMagick レジストリエントリに値を設定する
- 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 — 現在の画像ポインタから画像リストの最後までのすべての画像を取得し、結合する
- Imagick::solarizeImage — 画像にソラリゼーション効果を適用する
- Imagick::sparseColorImage — 色を補間する
- Imagick::spliceImage — 無地の画像を作成する
- Imagick::spreadImage — ブロック内の各ピクセルをランダムに移動する
- Imagick::statisticImage — 統計関数を使用して画像を変更する
- Imagick::steganoImage — デジタル透かしを画像に埋め込む
- Imagick::stereoImage — ふたつの画像を合成する
- Imagick::stripImage — 画像からすべてのプロパティやコメントを除去する
- Imagick::subImageMatch — 現在の画像から部分画像を検索し、類似度画像を返す
- Imagick::swirlImage — 画像の中心から、ピクセルを渦巻状にする
- Imagick::textureImage — テクスチャ画像をタイル状に並べる
- Imagick::thresholdImage — 閾値にもとづいて個々のピクセルの値を変更する
- Imagick::thumbnailImage — 画像のサイズを変更する
- Imagick::tintImage — 色ベクトルを画像の各ピクセルに適用する
- Imagick::__toString — 画像を文字列として返す
- Imagick::transformImage — 切り取るサイズと画像のジオメトリを設定する便利なメソッド
- Imagick::transformImageColorspace — 画像を新しい色空間に変換する
- 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 クラス

(PECL imagick 2, PECL imagick 3)

## クラス概要

class ImagickDraw {
public function affine(array `$affine`): bool
public function annotation(float `$x`, float `$y`, string `$text`): bool
public function arc(
float `$start_x`,
float `$start_y`,
float `$end_x`,
float `$end_y`,
float `$start_angle`,
float `$end_angle`
): bool
public function bezier(array `$coordinates`): bool
public function circle(
float `$origin_x`,
float `$origin_y`,
float `$perimeter_x`,
float `$perimeter_y`
): bool
public function clear(): bool
public function clone(): ImagickDraw
public function color(float `$x`, float `$y`, int `$paint`): bool
public function comment(string `$comment`): bool
public function composite(
int `$composite`,
float `$x`,
float `$y`,
float `$width`,
float `$height`,
Imagick `$image`
): bool
public function destroy(): bool
public function ellipse(
float `$origin_x`,
float `$origin_y`,
float `$radius_x`,
float `$radius_y`,
float `$angle_start`,
float `$angle_end`
): bool
public function getClipPath(): false|string
public function getClipRule(): int
public function getClipUnits(): int
public function getFillColor(): ImagickPixel
public function getFillOpacity(): float
public function getFillRule(): int
public function getFont(): string
public function getFontFamily(): string
public function getFontSize(): float
public function getFontStretch(): int
public function getFontStyle(): int
public function getFontWeight(): int
public function getGravity(): int
public function getStrokeAntialias(): bool
public function getStrokeColor(): ImagickPixel
public function getStrokeDashArray(): array
public function getStrokeDashOffset(): float
public function getStrokeLineCap(): int
public function getStrokeLineJoin(): int
public function getStrokeMiterLimit(): int
public function getStrokeOpacity(): float
public function getStrokeWidth(): float
public function getTextAlignment(): int
public function getTextAntialias(): bool
public function getTextDecoration(): int
public function getTextEncoding(): false|string
public function getTextInterlineSpacing(): float
public function getTextInterwordSpacing(): float
public function getTextKerning(): float
public function getTextUnderColor(): ImagickPixel
public function getVectorGraphics(): string
public function line(
float `$start_x`,
float `$start_y`,
float `$end_x`,
float `$end_y`
): bool
public function matte(float `$x`, float `$y`, int `$paint`): bool
public function pathClose(): bool
public function pathCurveToAbsolute(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
public function pathCurveToQuadraticBezierAbsolute(
float `$x1`,
float `$y1`,
float `$x_end`,
float `$y`
): bool
public function pathCurveToQuadraticBezierRelative(
float `$x1`,
float `$y1`,
float `$x_end`,
float `$y`
): bool
public function pathCurveToQuadraticBezierSmoothAbsolute(float `$x`, float `$y`): bool
public function pathCurveToQuadraticBezierSmoothRelative(float `$x`, float `$y`): bool
public function pathCurveToRelative(
float `$x1`,
float `$y1`,
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
public function pathCurveToSmoothAbsolute(
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
public function pathCurveToSmoothRelative(
float `$x2`,
float `$y2`,
float `$x`,
float `$y`
): bool
public function pathEllipticArcAbsolute(
float `$rx`,
float `$ry`,
float `$x_axis_rotation`,
bool `$large_arc`,
bool `$sweep`,
float `$x`,
float `$y`
): bool
public function pathEllipticArcRelative(
float `$rx`,
float `$ry`,
float `$x_axis_rotation`,
bool `$large_arc`,
bool `$sweep`,
float `$x`,
float `$y`
): bool
public function pathFinish(): bool
public function pathLineToAbsolute(float `$x`, float `$y`): bool
public function pathLineToHorizontalAbsolute(float `$x`): bool
public function pathLineToHorizontalRelative(float `$x`): bool
public function pathLineToRelative(float `$x`, float `$y`): bool
public function pathLineToVerticalAbsolute(float `$y`): bool
public function pathLineToVerticalRelative(float `$y`): bool
public function pathMoveToAbsolute(float `$x`, float `$y`): bool
public function pathMoveToRelative(float `$x`, float `$y`): bool
public function pathStart(): bool
public function point(float `$x`, float `$y`): bool
public function polygon(array `$coordinates`): bool
public function polyline(array `$coordinates`): bool
public function pop(): bool
public function popClipPath(): bool
public function popDefs(): bool
public function popPattern(): bool
public function push(): bool
public function pushClipPath(string `$clip_mask_id`): bool
public function pushDefs(): bool
public function pushPattern(
string `$pattern_id`,
float `$x`,
float `$y`,
float `$width`,
float `$height`
): bool
public function rectangle(
float `$top_left_x`,
float `$top_left_y`,
float `$bottom_right_x`,
float `$bottom_right_y`
): bool
public function render(): bool
public function resetVectorGraphics(): bool
public function rotate(float `$degrees`): bool
public function roundRectangle(
float `$top_left_x`,
float `$top_left_y`,
float `$bottom_right_x`,
float `$bottom_right_y`,
float `$rounding_x`,
float `$rounding_y`
): bool
public function scale(float `$x`, float `$y`): bool
public function setClipPath(string `$clip_mask`): bool
public function setClipRule(int `$fillrule`): bool
public function setClipUnits(int `$pathunits`): bool
public function setFillAlpha(float `$alpha`): bool
public function setFillColor(ImagickPixel|string `$fill_color`): bool
public function setFillOpacity(float `$opacity`): bool
public function setFillPatternURL(string `$fill_url`): bool
public function setFillRule(int `$fillrule`): bool
public function setFont(string `$font_name`): bool
public function setFontFamily(string `$font_family`): bool
public function setFontSize(float `$point_size`): bool
public function setFontStretch(int `$stretch`): bool
public function setFontStyle(int `$style`): bool
public function setFontWeight(int `$weight`): bool
public function setGravity(int `$gravity`): bool
public function setResolution(float `$resolution_x`, float `$resolution_y`): bool
public function setStrokeAlpha(float `$alpha`): bool
public function setStrokeAntialias(bool `$enabled`): bool
public function setStrokeColor(ImagickPixel|string `$color`): bool
public function setStrokeDashArray(?array `$dashes`): bool
public function setStrokeDashOffset(float `$dash_offset`): bool
public function setStrokeLineCap(int `$linecap`): bool
public function setStrokeLineJoin(int `$linejoin`): bool
public function setStrokeMiterLimit(int `$miterlimit`): bool
public function setStrokeOpacity(float `$opacity`): bool
public function setStrokePatternURL(string `$stroke_url`): bool
public function setStrokeWidth(float `$width`): bool
public function setTextAlignment(int `$align`): bool
public function setTextAntialias(bool `$antialias`): bool
public function setTextDecoration(int `$decoration`): bool
public function setTextEncoding(string `$encoding`): bool
public function setTextInterlineSpacing(float `$spacing`): bool
public function setTextInterwordSpacing(float `$spacing`): bool
public function setTextKerning(float `$kerning`): bool
public function setTextUnderColor(ImagickPixel|string `$under_color`): bool
public function setVectorGraphics(string `$xml`): bool
public function setViewbox(
int `$left_x`,
int `$top_y`,
int `$right_x`,
int `$bottom_y`
): bool
public function skewX(float `$degrees`): bool
public function skewY(float `$degrees`): bool
public function translate(float `$x`, float `$y`): bool
}

# ImagickDraw::affine

(PECL imagick 2, PECL imagick 3)

ImagickDraw::affine — 現在のアフィン変換行列を設定する

### 説明

public function 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::annotation

(PECL imagick 2, PECL imagick 3)

ImagickDraw::annotation — 画像上にテキストを描画する

### 説明

public function ImagickDraw::annotation(float `$x`, float `$y`, string `$text`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

画像上にテキストを描画します。

### パラメータ

`x`

  テキストを描画する x 座標。

`y`

  テキストを描画する y 座標。

`text`

  画像上に描画するテキスト。

### 戻り値

値を返しません。

# ImagickDraw::arc

(PECL imagick 2, PECL imagick 3)

ImagickDraw::arc — 円弧を描画する

### 説明

public function ImagickDraw::arc(
float `$start_x`,
float `$start_y`,
float `$end_x`,
float `$end_y`,
float `$start_angle`,
float `$end_angle`
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

画像上の指定した矩形内に円弧を描画します。

### パラメータ

`start_x`

  矩形の開始位置の x 座標。

`start_y`

  矩形の開始位置の y 座標。

`end_x`

  矩形の終了位置の x 座標。

`end_y`

  矩形の終了位置の y 座標。

`start_angle`

  開始位置の角度。

`end_angle`

  終了位置の角度。

### 戻り値

値を返しません。

### 例

例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::bezier

(PECL imagick 2, PECL imagick 3)

ImagickDraw::bezier — ベジエ曲線を描画する

### 説明

public function 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::circle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::circle — 円を描画する

### 説明

public function ImagickDraw::circle(
float `$origin_x`,
float `$origin_y`,
float `$perimeter_x`,
float `$perimeter_y`
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

画像上に円を描画します。

### パラメータ

`origin_x`

  原点の x 座標。

`origin_y`

  原点の y 座標。

`perimeter_x`

  周囲の x 座標。

`perimeter_y`

  周囲の 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::clear

(PECL imagick 2, PECL imagick 3)

ImagickDraw::clear — ImagickDraw をクリアする

### 説明

public function ImagickDraw::clear(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ImagickDraw オブジェクト上のコマンドをすべてクリアし、 デフォルト設定で初期化します。

### 戻り値

ImagickDraw オブジェクトを返します。

# ImagickDraw::clone

(PECL imagick 2, PECL imagick 3)

ImagickDraw::clone — 指定した ImagickDraw オブジェクトの完全なコピーを作成する

### 説明

public function ImagickDraw::clone(): ImagickDraw
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

指定した ImagickDraw オブジェクトの完全なコピーを作成します。

### 戻り値

指定した ImagickDraw オブジェクトの完全なコピーを返します。

# ImagickDraw::color

(PECL imagick 2, PECL imagick 3)

ImagickDraw::color — 画像上に色を描画する

### 説明

public function ImagickDraw::color(float `$x`, float `$y`, int `$paint`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の塗りつぶし色を使用して、 指定した開始位置から指定した方法で画像上に色を描画します。

### パラメータ

`x`

  描画位置の x 座標。

`y`

  描画位置の y 座標。

`paint`

  PAINT 定数 (`imagick::PAINT_*`) のいずれか

### 戻り値

値を返しません。

# ImagickDraw::comment

(PECL imagick 2, PECL imagick 3)

ImagickDraw::comment — コメントを追加する

### 説明

public function ImagickDraw::comment(string `$comment`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ベクター出力ストリームにコメントを追加します。

### パラメータ

`comment`

  ベクター出力ストリームに追加するコメント文字列。

### 戻り値

値を返しません。

# ImagickDraw::composite

(PECL imagick 2, PECL imagick 3)

ImagickDraw::composite — 現在の画像上に別の画像を合成する

### 説明

public function ImagickDraw::composite(
int `$composite`,
float `$x`,
float `$y`,
float `$width`,
float `$height`,
Imagick `$image`
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の画像上に別の画像を合成します。 合成演算子、位置、サイズを指定します。

### パラメータ

`composite`

  合成演算子 (`imagick::COMPOSITE_*`) のいずれか

`x`

  左上角の x 座標。

`y`

  左上角の y 座標。

`width`

  合成する画像の幅。

`height`

  合成する画像の高さ。

`image`

  合成する画像を取得する 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::__construct

(PECL imagick 2, PECL imagick 3)

ImagickDraw::__construct — ImagickDraw コンストラクタ

### 説明

public function ImagickDraw::__construct()
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ImagickDraw のコンストラクタです。

### 戻り値

値を返しません。

# ImagickDraw::destroy

(PECL imagick 2, PECL imagick 3)

ImagickDraw::destroy — 関連付けられたすべてのリソースを開放する

### 説明

public function ImagickDraw::destroy(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

この ImagickDraw オブジェクトに関連付けられたすべてのリソースを開放します。

### 戻り値

値を返しません。

# ImagickDraw::ellipse

(PECL imagick 2, PECL imagick 3)

ImagickDraw::ellipse — 画像上に楕円を描画する

### 説明

public function ImagickDraw::ellipse(
float `$origin_x`,
float `$origin_y`,
float `$radius_x`,
float `$radius_y`,
float `$angle_start`,
float `$angle_end`
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

画像上に楕円を描画します。

### パラメータ

`origin_x`

`origin_y`

`radius_x`

`radius_y`

`angle_start`

`angle_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();
    }

    ?>

# ImagickDraw::getClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getClipPath — 現在のクリッピングパスの ID を取得する

### 説明

public function ImagickDraw::getClipPath(): false|string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在のクリッピングパスの ID を取得します。

### 戻り値

クリッピングパスの ID を含む文字列、あるいはパスが存在しない場合に false を返します。

# ImagickDraw::getClipRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getClipRule — 現在の多角形塗りつぶしルールを返す

### 説明

public function ImagickDraw::getClipRule(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

クリッピングパスで使用されている、現在の多角形塗りつぶしルールを返します。

### 戻り値

FILLRULE 定数 (`imagick::FILLRULE_*`) のいずれかを返します。

# ImagickDraw::getClipUnits

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getClipUnits — クリップパスの単位の解釈を返す

### 説明

public function ImagickDraw::getClipUnits(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

クリップパスの単位の解釈を返します。

### 戻り値

成功した場合に整数値を返します。

# ImagickDraw::getFillColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFillColor — 塗りつぶし色を返す

### 説明

public function ImagickDraw::getFillColor(): ImagickPixel
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

描画オブジェクトで使用する塗りつぶし色を返します。

### 戻り値

ImagickPixel オブジェクトを返します。

# ImagickDraw::getFillOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFillOpacity — 描画時の透過度を返す

### 説明

public function ImagickDraw::getFillOpacity(): float
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

色やテクスチャによる塗りつぶしの際の透過度を返します。 完全に不透過の場合は 1.0 となります。

### 戻り値

透過度を返します。

# ImagickDraw::getFillRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFillRule — 塗りつぶしルールを返す

### 説明

public function ImagickDraw::getFillRule(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

多角形の描画時に使用する塗りつぶしルールを返します。

### 戻り値

FILLRULE 定数 (`imagick::FILLRULE_*`) を返します。

# ImagickDraw::getFont

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFont — フォントを返す

### 説明

public function ImagickDraw::getFont(): string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントを文字列で返します。

### 戻り値

成功した場合に文字列、フォントが設定されていない場合に false を返します。

# ImagickDraw::getFontFamily

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontFamily — フォントファミリーを返す

### 説明

public function ImagickDraw::getFontFamily(): string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントファミリーを返します。

### 戻り値

現在選択されているフォントファミリー、 あるいはフォントファミリーが設定されていない場合に false を返します。

# ImagickDraw::getFontSize

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontSize — フォントのポイント数を返す

### 説明

public function ImagickDraw::getFontSize(): float
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントのポイント数を返します。

### 戻り値

現在の ImagickDraw オブジェクトに関連付けられているフォントのサイズを返します。

# ImagickDraw::getFontStretch

(PECL imagick 2 >=2.3.0, PECL imagick 3)

ImagickDraw::getFontStretch — テキストによる注記を行う際に使用するフォントの伸縮を取得する

### 説明

public function ImagickDraw::getFontStretch(): int

テキストによる注記を行う際に使用するフォントの伸縮を取得します。 StretchType を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# ImagickDraw::getFontStyle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontStyle — フォントのスタイルを返す

### 説明

public function ImagickDraw::getFontStyle(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントのスタイルを返します。

### 戻り値

ImagickDraw オブジェクトに関連付けられたフォントの スタイル を表す定数(`imagick::STYLE_*`)、 あるいはスタイルが設定されていない場合に 0 を返します。

# ImagickDraw::getFontWeight

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getFontWeight — フォントの重さを返す

### 説明

public function ImagickDraw::getFontWeight(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントの重さを返します。

### 戻り値

成功した場合に整数値、重さが設定されていない場合に 0 を返します。

# ImagickDraw::getGravity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getGravity — テキストの配置時の gravity を返す

### 説明

public function ImagickDraw::getGravity(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するテキスト配置の gravity を返します。

### 戻り値

成功時に、GRAVITY 定数 (`imagick::GRAVITY_*`) を返します。 gravity が設定されていない場合は 0 を返します。

# ImagickDraw::getStrokeAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeAntialias — 現在の縁取りのアンチエイリアス設定を返す

### 説明

public function ImagickDraw::getStrokeAntialias(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の縁取りのアンチエイリアス設定を返します。 縁取りの枠線は、デフォルトでアンチエイリアス処理が行われます。 アンチエイリアスを無効にすると、 縁取りの描画時には縁取り色あるいはキャンバスの色のどちらかが用いられることになります。

### 戻り値

アンチエイリアスがオンの場合に `true`、オフの場合に `false` を返します。

# ImagickDraw::getStrokeColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeColor — オブジェクトの縁取りに使用する色を返す

### 説明

public function ImagickDraw::getStrokeColor(): ImagickPixel
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの縁取りに使用する色を返します。

### パラメータ

`stroke_color`

### 戻り値

色を表す ImagickPixel オブジェクトを返します。

# ImagickDraw::getStrokeDashArray

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeDashArray — パスの描画に使用する破線のパターンを表す配列を返す

### 説明

public function ImagickDraw::getStrokeDashArray(): array
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パスの描画に使用する破線のパターンを表す配列を返します。

### 戻り値

成功した場合に配列、設定されていない場合は空の配列を返します。

# ImagickDraw::getStrokeDashOffset

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeDashOffset — 破線パターンにおける破線の開始オフセットを返す

### 説明

public function ImagickDraw::getStrokeDashOffset(): float
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

破線パターンにおける破線の開始オフセットを返します。

### 戻り値

オフセットを表す float 値、あるいは設定されていない場合に 0 を返します。

# ImagickDraw::getStrokeLineCap

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeLineCap — 開かれたサブパスを描画する際に使用する端点の形状を返す

### 説明

public function ImagickDraw::getStrokeLineCap(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

開かれたサブパスを描画する際に使用する端点の形状を返します。

### 戻り値

LINECAP 定数 (`imagick::LINECAP_*`) を返します。 あるいは設定されていない場合に 0 を返します。

# ImagickDraw::getStrokeLineJoin

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeLineJoin — パスの角を描画する際に使用する形状を返す

### 説明

public function ImagickDraw::getStrokeLineJoin(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パス (あるいはその他のベクター図形) の角を描画する際に使用する形状を返します。

### 戻り値

LINEJOIN 定数 (`imagick::LINEJOIN_*`) を返します。 あるいは設定されていない場合に 0 を返します。

# ImagickDraw::getStrokeMiterLimit

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeMiterLimit — マイターリミットを返す

### 説明

public function ImagickDraw::getStrokeMiterLimit(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

マイターリミットを返します。 2 本の直線が小さい角度で連結され、かつ連結方法が 'lineJoin' に設定されている場合、 出来上がる線の角の部分が非常に長くなります。'miterLimit' は、miter length (角の長さ) と 'lineWidth' の比率の最大値です。

### 戻り値

マイターリミットを表す整数値、あるいは マイターリミットが設定されていない場合に 0 を返します。

# ImagickDraw::getStrokeOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeOpacity — オブジェクトの枠線の透明度を返す

### 説明

public function ImagickDraw::getStrokeOpacity(): float
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの枠線の透明度を返します。

### 戻り値

透明度を表す float 型の値を返します。

# ImagickDraw::getStrokeWidth

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getStrokeWidth — オブジェクトの枠線の描画に使用する線の幅を返す

### 説明

public function ImagickDraw::getStrokeWidth(): float
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの枠線の描画に使用する線の幅を返します。

### 戻り値

線幅を表す float 型の値を返します。

# ImagickDraw::getTextAlignment

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextAlignment — テキストの配置を返す

### 説明

public function ImagickDraw::getTextAlignment(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際の配置を返します。

### 戻り値

ALIGN 定数 (`imagick::ALIGN_*`) を返します。 あるいは設定されていない場合に 0 を返します。

# ImagickDraw::getTextAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextAntialias — 現在のテキストのアンチエイリアス設定を返す

### 説明

public function ImagickDraw::getTextAntialias(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在のテキストのアンチエイリアス設定を返します。 これは、テキストのアンチエイリアス処理を行うかどうかを表すものです。 デフォルトでは、テキストのアンチエイリアス処理が行われます。

### 戻り値

テキストをアンチエイリアス処理する場合に `true`、 ない場合に `false` を返します。

# ImagickDraw::getTextDecoration

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextDecoration — テキストの装飾を返す

### 説明

public function ImagickDraw::getTextDecoration(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に適用する装飾を返します。

### 戻り値

DECORATION 定数 (`imagick::DECORATION_*`) を返します。 あるいは装飾が設定されていない場合に 0 を返します。

# ImagickDraw::getTextEncoding

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextEncoding — テキストによる注記の際に使用するコードセットを返す

### 説明

public function ImagickDraw::getTextEncoding(): false|string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するコードセットを表す文字列を返します。

### 戻り値

コードセットを表す文字列、 あるいはエンコーディングが設定されていない場合に false を返します。

# ImagickDraw::getTextInterlineSpacing

(PECL imagick 3 >= 3.1.0)

ImagickDraw::getTextInterlineSpacing — テキストの行間スペースを取得する

### 説明

public function ImagickDraw::getTextInterlineSpacing(): float

テキストの行間スペースを取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# ImagickDraw::getTextInterwordSpacing

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.1.0)

ImagickDraw::getTextInterwordSpacing — テキストの単語間のスペースを取得する

### 説明

public function ImagickDraw::getTextInterwordSpacing(): float

テキストの単語間のスペースを取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# ImagickDraw::getTextKerning

(PECL imagick 2 >= 2.3.0, PECL imagick 3 >= 3.1.0)

ImagickDraw::getTextKerning — テキストのカーニングを取得する

### 説明

public function ImagickDraw::getTextKerning(): float

テキストのカーニングを取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# ImagickDraw::getTextUnderColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getTextUnderColor — テキストの背景色を返す

### 説明

public function ImagickDraw::getTextUnderColor(): ImagickPixel
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記の背景に置く矩形の色を返します。

### 戻り値

色を表す ImagickPixel オブジェクトを返します。

# ImagickDraw::getVectorGraphics

(PECL imagick 2, PECL imagick 3)

ImagickDraw::getVectorGraphics — ベクターグラフィックを含む文字列を返す

### 説明

public function ImagickDraw::getVectorGraphics(): string
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ImagickDraw オブジェクトのインスタンスが作成された後で、 グラフィックメソッドのコールによってできあがったベクターグラフィックを文字列で返します。

### 戻り値

ベクターグラフィックを文字列で返します。

# ImagickDraw::line

(PECL imagick 2, PECL imagick 3)

ImagickDraw::line — 直線を描画する

### 説明

public function ImagickDraw::line(
float `$start_x`,
float `$start_y`,
float `$end_x`,
float `$end_y`
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の描画色、透明度そして線幅を使用して画像上に直線を描画します。

### パラメータ

`start_x`

  開始位置の x 座標。

`start_y`

  開始位置の y 座標。

`end_x`

  終了位置の x 座標。

`end_y`

  終了位置の 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();
    }

    ?>

# ImagickDraw::matte

(PECL imagick 2, PECL imagick 3)

ImagickDraw::matte — 画像の opacity チャネル上に描画する

### 説明

public function ImagickDraw::matte(float `$x`, float `$y`, int `$paint`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

画像の opacity チャネル上に描画し、ピクセルの透過度に影響を与えます。

### パラメータ

`x`

  マットの x 座標。

`y`

  マットの y 座標。

`paint`

  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::pathClose

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathClose — パス要素を現在のパスに追加する

### 説明

public function ImagickDraw::pathClose(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パス要素を現在のパスに追加し、 現在の点から現在のサブパスの直近の開始点 (通常は、直近の moveto の点となります) に直線を引くことで現在のパスを閉じます。

### 戻り値

値を返しません。

# ImagickDraw::pathCurveToAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToAbsolute — 三次ベジエ曲線を描画する

### 説明

public function 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::pathCurveToQuadraticBezierAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierAbsolute — 二次ベジエ曲線を描画する

### 説明

public function ImagickDraw::pathCurveToQuadraticBezierAbsolute(
float `$x1`,
float `$y1`,
float `$x_end`,
float `$y`
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から (x,y) までの二次ベジエ曲線を描画します。 制御点を (x1,y1) とし、絶対座標で指定します。このコマンドが終了した後は、 現在の位置は polybezier が使用する最後の (x,y) 座標の組となります。

### パラメータ

`x1`

  制御点の x 座標。

`y1`

  制御点の y 座標。

`x_end`

  終点の 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::pathCurveToQuadraticBezierRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierRelative — 二次ベジエ曲線を描画する

### 説明

public function ImagickDraw::pathCurveToQuadraticBezierRelative(
float `$x1`,
float `$y1`,
float `$x_end`,
float `$y`
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から (x,y) までの二次ベジエ曲線を描画します。 制御点を (x1,y1) とし、相対座標で指定します。このコマンドが終了した後は、 現在の位置は polybezier が使用する最後の (x,y) 座標の組となります。

### パラメータ

`x1`

  始点の x 座標。

`y1`

  始点の y 座標。

`x_end`

  終点の x 座標。

`y`

  終点の y 座標。

### 戻り値

値を返しません。

# ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierSmoothAbsolute — 二次ベジエ曲線を描画する

### 説明

public function 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::pathCurveToQuadraticBezierSmoothRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToQuadraticBezierSmoothRelative — 二次ベジエ曲線を描画する

### 説明

public function 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::pathCurveToRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToRelative — 三次ベジエ曲線を描画する

### 説明

public function 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::pathCurveToSmoothAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToSmoothAbsolute — 三次ベジエ曲線を描画する

### 説明

public function 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::pathCurveToSmoothRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathCurveToSmoothRelative — 三次ベジエ曲線を描画する

### 説明

public function 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::pathEllipticArcAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathEllipticArcAbsolute — 楕円弧を描画する

### 説明

public function ImagickDraw::pathEllipticArcAbsolute(
float `$rx`,
float `$ry`,
float `$x_axis_rotation`,
bool `$large_arc`,
bool `$sweep`,
float `$x`,
float `$y`
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の位置から (x, y) まで、絶対座標を使用して楕円弧を描画します。 楕円の大きさと方向は、2 つの半径 (rx, ry) と xAxisRotation で決まります。xAxisRotation は、楕円全体を座標系に対してどれだけ回転させるかを表すものです。 楕円の中心 (cx, cy) は、その他のパラメータの値から自動的に算出されます。 largeArcFlag および sweepFlag は自動計算を支援するためのもので、 楕円の描画方法を定義します。 `large_arc` が `true` の場合は考えうる楕円のうち大きいほうを描画します。 `sweep` が `true` の場合は時計回りの回転で楕円を描画します。

### パラメータ

`rx`

  x 方向の半径。

`ry`

  y 方向の半径。

`x_axis_rotation`

  x 軸の回転。

`large_arc`

  large arc フラグ。

`sweep`

  sweep フラグ。

`x`

  x 座標。

`y`

  y 座標。

### 戻り値

値を返しません。

# ImagickDraw::pathEllipticArcRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathEllipticArcRelative — 楕円弧を描画する

### 説明

public function ImagickDraw::pathEllipticArcRelative(
float `$rx`,
float `$ry`,
float `$x_axis_rotation`,
bool `$large_arc`,
bool `$sweep`,
float `$x`,
float `$y`
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の位置から (x, y) まで、相対座標を使用して楕円弧を描画します。 楕円の大きさと方向は、2 つの半径 (rx, ry) と xAxisRotation で決まります。xAxisRotation は、楕円全体を座標系に対してどれだけ回転させるかを表すものです。 楕円の中心 (cx, cy) は、その他のパラメータの値から自動的に算出されます。 largeArcFlag および sweepFlag は自動計算を支援するためのもので、 楕円の描画方法を定義します。 `large_arc` が `true` の場合は考えうる楕円のうち大きいほうを描画します。 `sweep` が `true` の場合は時計回りの回転で楕円を描画します。

### パラメータ

`rx`

  x 方向の半径。

`ry`

  y 方向の半径。

`x_axis_rotation`

  x 軸の回転。

`large_arc`

  large arc フラグ。

`sweep`

  sweep フラグ。

`x`

  x 座標。

`y`

  y 座標。

### 戻り値

値を返しません。

# ImagickDraw::pathFinish

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathFinish — 現在のパスを終了する

### 説明

public function ImagickDraw::pathFinish(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在のパスを終了します。

### 戻り値

値を返しません。

# ImagickDraw::pathLineToAbsolute

(PECL imagick 2)

ImagickDraw::pathLineToAbsolute — 直線パスを描画する

### 説明

public function ImagickDraw::pathLineToAbsolute(float `$x`, float `$y`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から指定した座標まで、絶対座標を使用して直線を描画します。 座標は新しい点に移動します。

### パラメータ

`x`

  始点の x 座標。

`y`

  終点の x 座標。

### 戻り値

値を返しません。

# ImagickDraw::pathLineToHorizontalAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToHorizontalAbsolute — 水平直線パスを描画する

### 説明

public function ImagickDraw::pathLineToHorizontalAbsolute(float `$x`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から指定した座標まで、絶対座標を使用して水平直線を描画します。 座標は新しい点に移動します。

### パラメータ

`x`

  x 座標。

### 戻り値

値を返しません。

# ImagickDraw::pathLineToHorizontalRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToHorizontalRelative — 水平直線パスを描画する

### 説明

public function ImagickDraw::pathLineToHorizontalRelative(float `$x`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から指定した座標まで、相対座標を使用して水平直線を描画します。 座標は新しい点に移動します。

### パラメータ

`x`

  x 座標。

### 戻り値

値を返しません。

# ImagickDraw::pathLineToRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToRelative — 直線パスを描画する

### 説明

public function ImagickDraw::pathLineToRelative(float `$x`, float `$y`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から指定した座標まで、相対座標を使用して直線を描画します。 座標は新しい点に移動します。

### パラメータ

`x`

  始点の x 座標。

`y`

  始点の y 座標。

### 戻り値

値を返しません。

# ImagickDraw::pathLineToVerticalAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToVerticalAbsolute — 垂直直線パスを描画する

### 説明

public function ImagickDraw::pathLineToVerticalAbsolute(float `$y`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から指定した座標まで、絶対座標を使用して垂直直線を描画します。 座標は新しい点に移動します。

### パラメータ

`y`

  y 座標。

### 戻り値

値を返しません。

# ImagickDraw::pathLineToVerticalRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathLineToVerticalRelative — 垂直直線パスを描画する

### 説明

public function ImagickDraw::pathLineToVerticalRelative(float `$y`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

現在の点から指定した座標まで、相対座標を使用して垂直直線を描画します。 座標は新しい点に移動します。

### パラメータ

`y`

  y 座標。

### 戻り値

値を返しません。

# ImagickDraw::pathMoveToAbsolute

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathMoveToAbsolute — 新しいサブパスを開始する

### 説明

public function ImagickDraw::pathMoveToAbsolute(float `$x`, float `$y`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

絶対座標で指定した座標から、新しいサブパスを開始します。 現在の点は指定した座標となります。

### パラメータ

`x`

  始点の x 座標。

`y`

  始点の y 座標。

### 戻り値

値を返しません。

# ImagickDraw::pathMoveToRelative

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathMoveToRelative — 新しいサブパスを開始する

### 説明

public function ImagickDraw::pathMoveToRelative(float `$x`, float `$y`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

相対座標で指定した座標から、新しいサブパスを開始します。 現在の点は指定した座標となります。

### パラメータ

`x`

  始点の x 座標。

`y`

  始点の y 座標。

### 戻り値

値を返しません。

# ImagickDraw::pathStart

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pathStart — パス描画リストの開始を宣言する

### 説明

public function 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::point

(PECL imagick 2, PECL imagick 3)

ImagickDraw::point — 点を描画する

### 説明

public function 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::polygon

(PECL imagick 2, PECL imagick 3)

ImagickDraw::polygon — 多角形を描画する

### 説明

public function 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::polyline

(PECL imagick 2, PECL imagick 3)

ImagickDraw::polyline — 線分群を描画する

### 説明

public function 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::pop

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pop — スタック内の現在の ImagickDraw を破棄し、事前に push された ImagickDraw を返す

### 説明

public function ImagickDraw::pop(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

スタック内の現在の ImagickDraw を破棄し、事前に push された ImagickDraw を返します。 複数の ImagickDraw が存在する可能性もあります。 push された回数より多くの ImagickDraw の pop を試みるとエラーとなります。 また、ImagickDrow が push されたときと同じ方式で pop する必要があります。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

# ImagickDraw::popClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::popClipPath — クリップパスの定義を終了する

### 説明

public function ImagickDraw::popClipPath(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

クリップパスの定義を終了します。

### 戻り値

値を返しません。

# ImagickDraw::popDefs

(PECL imagick 2, PECL imagick 3)

ImagickDraw::popDefs — 定義リストを終了する

### 説明

public function 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::popPattern

(PECL imagick 2, PECL imagick 3)

ImagickDraw::popPattern — パターン定義を終了する

### 説明

public function ImagickDraw::popPattern(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

パターン定義を終了します。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

# ImagickDraw::push

(PECL imagick 2, PECL imagick 3)

ImagickDraw::push — 現在の ImagickDraw をコピーしてスタックに格納する

### 説明

public function 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::pushClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pushClipPath — クリップパスの定義を開始する

### 説明

public function ImagickDraw::pushClipPath(string `$clip_mask_id`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

クリップパスの定義を開始します。 これは、任意の数の描画コマンドで構成され、最後は ImagickDraw::popClipPath() コマンドとなります。

### パラメータ

`clip_mask_id`

  クリップマスク ID。

### 戻り値

値を返しません。

# ImagickDraw::pushDefs

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pushDefs — 後に続くコマンドが、処理の前に名前つき要素を作成することを示す

### 説明

public function ImagickDraw::pushDefs(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

後に続く ImagickDraw::popDefs() までのコマンドが、 名前つき要素 (クリップパスやテクスチャなど) を作成することを示します。 これは、効率を考慮して事前に処理されます。

### 戻り値

値を返しません。

# ImagickDraw::pushPattern

(PECL imagick 2, PECL imagick 3)

ImagickDraw::pushPattern — 後に続く ImagickDraw::opPattern() までのコマンドが、名前付きパターンを構成することを示す

### 説明

public function 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::rectangle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::rectangle — 矩形を描画する

### 説明

public function ImagickDraw::rectangle(
float `$top_left_x`,
float `$top_left_y`,
float `$bottom_right_x`,
float `$bottom_right_y`
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

2 つの座標を与え、現在の枠線や線幅、塗りつぶしの設定を使用して矩形を描画します。

### パラメータ

`top_left_x`

  左上の角の x 座標。

`top_left_y`

  左上の角の y 座標。

`bottom_right_x`

  右下の角の x 座標。

`bottom_right_y`

  右下の角の 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::render

(PECL imagick 2, PECL imagick 3)

ImagickDraw::render — これまでのすべての描画コマンドを画像上にレンダリングする

### 説明

public function ImagickDraw::render(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

これまでのすべての描画コマンドを画像上にレンダリングします。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

# ImagickDraw::resetVectorGraphics

(PECL imagick 2, PECL imagick 3)

ImagickDraw::resetVectorGraphics — ベクターグラフィックをリセットする

### 説明

public function ImagickDraw::resetVectorGraphics(): bool

ベクターグラフィックをリセットします。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

成功した場合に `true` を返します。

# ImagickDraw::rotate

(PECL imagick 2, PECL imagick 3)

ImagickDraw::rotate — 指定した回転を現在の座標空間に適用する

### 説明

public function 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::roundRectangle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::roundRectangle — 角が丸い矩形を描画する

### 説明

public function ImagickDraw::roundRectangle(
float `$top_left_x`,
float `$top_left_y`,
float `$bottom_right_x`,
float `$bottom_right_y`,
float `$rounding_x`,
float `$rounding_y`
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

2 つの座標、そして角の x & y 方向の丸めを与え、 現在の枠線や線幅、塗りつぶしの設定を使用して角が丸い矩形を描画します。

### パラメータ

`top_left_x`

  左上の角の x 座標。

`top_left_y`

  左上の角の y 座標。

`bottom_right_x`

  右下の角の x 座標。

`bottom_right_y`

  右下の角の y 座標。

`rounding_x`

  x 方向の丸め。

`rounding_y`

  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::scale

(PECL imagick 2, PECL imagick 3)

ImagickDraw::scale — 倍率を調整する

### 説明

public function 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::setClipPath

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setClipPath — 指定した名前のクリッピングパスを画像に関連付ける

### 説明

public function 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::setClipRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setClipRule — クリッピングパスで使用する多角形塗りつぶしルールを設定する

### 説明

public function ImagickDraw::setClipRule(int `$fillrule`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

クリッピングパスで使用する多角形塗りつぶしルールを設定します。

### パラメータ

`fillrule`

  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::setClipUnits

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setClipUnits — クリップパスの単位の解釈を設定する

### 説明

public function ImagickDraw::setClipUnits(int `$pathunits`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

クリップパスの単位の解釈を設定します。

### パラメータ

`pathunits`

  クリップ単位の数。

### 戻り値

値を返しません。

### 例

例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::setFillAlpha

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillAlpha — 色やテクスチャによる塗りつぶしの際の透過度を設定する

### 説明

public function ImagickDraw::setFillAlpha(float `$alpha`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

色やテクスチャによる塗りつぶしの際の透過度を設定します。 完全に不透明な状態が 1.0 となります。

### パラメータ

`alpha`

  塗りつぶしのアルファ値。

### 戻り値

値を返しません。

### 例

例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::setFillColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillColor — オブジェクトの塗りつぶしに使用する色を設定する

### 説明

public function ImagickDraw::setFillColor(ImagickPixel|string `$fill_color`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの塗りつぶしに使用する色を設定します。

### パラメータ

`fill_color`

  色を表す 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::setFillOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillOpacity — 色やテクスチャによる塗りつぶしの際の透過度を設定する

### 説明

public function ImagickDraw::setFillOpacity(float `$opacity`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

色やテクスチャによる塗りつぶしの際の透過度を設定します。 完全に不透明な状態が 1.0 となります。

### パラメータ

`opacity`

  塗りつぶしの透明度。

### 戻り値

値を返しません。

### 例

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

    ?>

# ImagickDraw::setFillPatternURL

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillPatternURL — オブジェクトの塗りつぶしパターンとして使用する URL を設定する

### 説明

public function ImagickDraw::setFillPatternURL(string `$fill_url`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの塗りつぶしパターンとして使用する URL を設定します。 現時点でサポートしているのは、ローカル URL ("#identifier") のみです。 このローカル URL は、DrawPushPattern/DrawPopPattern で塗りつぶしパターンを定義することによって作成されます。

### パラメータ

`fill_url`

  塗りつぶしパターンを取得する URL。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

# ImagickDraw::setFillRule

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFillRule — 多角形の描画時に使用する塗りつぶしルールを設定する

### 説明

public function ImagickDraw::setFillRule(int `$fillrule`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

多角形の描画時に使用する塗りつぶしルールを設定します。

### パラメータ

`fillrule`

  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::setFont

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFont — テキストによる注記を行う際に使用するフォントを設定する

### 説明

public function 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::setFontFamily

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontFamily — テキストによる注記を行う際に使用するフォントファミリーを設定する

### 説明

public function 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::setFontSize

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontSize — テキストによる注記を行う際に使用するフォントのポイント数を設定する

### 説明

public function ImagickDraw::setFontSize(float `$point_size`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントのポイント数を設定します。

### パラメータ

`point_size`

  ポイント数。

### 戻り値

値を返しません。

### 例

例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::setFontStretch

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontStretch — テキストによる注記を行う際に使用するフォントの伸縮を設定する

### 説明

public function ImagickDraw::setFontStretch(int `$stretch`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントの伸縮を設定します。 AnyStretch は、ワイルドカードの "don't care" オプションとして働きます。

### パラメータ

`stretch`

  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::setFontStyle

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontStyle — テキストによる注記を行う際に使用するフォントのスタイルを設定する

### 説明

public function 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::setFontWeight

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setFontWeight — フォントの重さを設定する

### 説明

public function ImagickDraw::setFontWeight(int `$weight`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するフォントの重さを設定します。

### パラメータ

`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();
    }

    ?>

# ImagickDraw::setGravity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setGravity — テキストの配置時の gravity を設定する

### 説明

public function 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();
    }

    ?>

# ImagickDraw::setResolution

(PECL imagick 3 >= 3.1.0)

ImagickDraw::setResolution — 解像度を設定する

### 説明

public function ImagickDraw::setResolution(float `$resolution_x`, float `$resolution_y`): bool

解像度を設定します。

### パラメータ

`resolution_x`

`resolution_y`

### 戻り値

成功した場合に `true` を返します。

# ImagickDraw::setStrokeAlpha

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeAlpha — オブジェクトの枠線の透明度を指定する

### 説明

public function ImagickDraw::setStrokeAlpha(float `$alpha`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの枠線の透明度を指定します。

### パラメータ

`alpha`

  透明度。

### 戻り値

値を返しません。

### 例

例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::setStrokeAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeAntialias — 縁取りの枠線をアンチエイリアス処理するかどうかを制御する

### 説明

public function ImagickDraw::setStrokeAntialias(bool `$enabled`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

縁取りの枠線をアンチエイリアス処理するかどうかを制御します。 縁取りの枠線は、デフォルトでアンチエイリアス処理が行われます。 アンチエイリアスを無効にすると、 縁取りの描画時には縁取り色あるいはキャンバスの色のどちらかが用いられることになります。

### パラメータ

`enabled`

  アンチエイリアス設定。

### 戻り値

値を返しません。

### 例

例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::setStrokeColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeColor — オブジェクトの縁取りに使用する色を設定する

### 説明

public function ImagickDraw::setStrokeColor(ImagickPixel|string `$color`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの縁取りに使用する色を設定します。

### パラメータ

`color`

  縁取り色。

### 戻り値

値を返しません。

### 例

例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::setStrokeDashArray

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeDashArray — パスの描画に使用する破線のパターンを指定する

### 説明

public function ImagickDraw::setStrokeDashArray(?array `$dashes`): 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 となります。

### パラメータ

`dashes`

  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::setStrokeDashOffset

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeDashOffset — 破線パターンにおける破線の開始オフセットを指定する

### 説明

public function 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::setStrokeLineCap

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeLineCap — 開かれたサブパスを描画する際に使用する端点の形状を指定する

### 説明

public function 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::setStrokeLineJoin

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeLineJoin — パスの角を描画する際に使用する形状を指定する

### 説明

public function 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::setStrokeMiterLimit

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeMiterLimit — マイターリミットを指定する

### 説明

public function 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::setStrokeOpacity

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeOpacity — オブジェクトの枠線の透明度を指定する

### 説明

public function ImagickDraw::setStrokeOpacity(float `$opacity`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの枠線の透明度を指定します。

### パラメータ

`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::setStrokePatternURL

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokePatternURL — オブジェクトの枠線の描画に使用するパターンを設定する

### 説明

public function ImagickDraw::setStrokePatternURL(string `$stroke_url`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの枠線の描画に使用するパターンを設定します。

### パラメータ

`stroke_url`

  URL。

### 戻り値

成功した場合に `true` を返します。

# ImagickDraw::setStrokeWidth

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setStrokeWidth — オブジェクトの枠線の描画に使用する線の幅を設定する

### 説明

public function ImagickDraw::setStrokeWidth(float `$width`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

オブジェクトの枠線の描画に使用する線の幅を設定します。

### パラメータ

`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::setTextAlignment

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextAlignment — テキストの配置を指定する

### 説明

public function ImagickDraw::setTextAlignment(int `$align`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際の配置を指定します。

### パラメータ

`align`

  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::setTextAntialias

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextAntialias — テキストをアンチエイリアス処理するかどうかを制御する

### 説明

public function 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::setTextDecoration

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextDecoration — 装飾を指定する

### 説明

public function 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::setTextEncoding

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextEncoding — テキストのコードセットを指定する

### 説明

public function ImagickDraw::setTextEncoding(string `$encoding`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

テキストによる注記を行う際に使用するコードセットを指定します。 現時点で指定できるエンコーディングは "UTF-8" のみで、 これはバイトシーケンスを Unicode で表記したものです。 空文字列を指定すると、システムのデフォルトを使用します。 Unicode によるテキストの注記を行うには、 Unicode をサポートしたフォントが必要です。

### パラメータ

`encoding`

  エンコーディング名。

### 戻り値

値を返しません。

# ImagickDraw::setTextInterlineSpacing

(PECL imagick 3 >= 3.1.0)

ImagickDraw::setTextInterlineSpacing — テキストの行間スペースを設定する

### 説明

public function ImagickDraw::setTextInterlineSpacing(float `$spacing`): bool

テキストの行間スペースを設定します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`spacing`

### 戻り値

成功した場合に `true` を返します。

# ImagickDraw::setTextInterwordSpacing

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickDraw::setTextInterwordSpacing — テキストの単語間のスペースを設定する

### 説明

public function ImagickDraw::setTextInterwordSpacing(float `$spacing`): bool

テキストの単語間のスペースを設定します。

### パラメータ

`spacing`

### 戻り値

成功した場合に `true` を返します。

# ImagickDraw::setTextKerning

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickDraw::setTextKerning — テキストのカーニングを設定する

### 説明

public function ImagickDraw::setTextKerning(float `$kerning`): bool

テキストのカーニングを設定します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`kerning`

### 戻り値

成功した場合に `true` を返します。

# ImagickDraw::setTextUnderColor

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setTextUnderColor — 背景の矩形の色を指定する

### 説明

public function ImagickDraw::setTextUnderColor(ImagickPixel|string `$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::setVectorGraphics

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setVectorGraphics — ベクターグラフィックを設定する

### 説明

public function 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::setViewbox

(PECL imagick 2, PECL imagick 3)

ImagickDraw::setViewbox — キャンバス全体の大きさを設定する

### 説明

public function ImagickDraw::setViewbox(
int `$left_x`,
int `$top_y`,
int `$right_x`,
int `$bottom_y`
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ベクターデータの描画に使用するキャンバスの大きさを設定します。 通常は、これはキャンバス画像と同じ大きさに設定します。 ベクターデータを SVG や MVG 形式で保存する際に、 これを使用してキャンバス画像の大きさを指定します。 またビューアがベクターデータをレンダリングする際にもこれを使用します。

### パラメータ

`left_x`

  左の x 座標。

`top_y`

  左の y 座標。

`right_x`

  右の x 座標。

`bottom_y`

  右の 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::skewX

(PECL imagick 2, PECL imagick 3)

ImagickDraw::skewX — 現在の座標系を水平方向に傾ける

### 説明

public function 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::skewY

(PECL imagick 2, PECL imagick 3)

ImagickDraw::skewY — 現在の座標系を垂直方向に傾ける

### 説明

public function 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::translate

(PECL imagick 2, PECL imagick 3)

ImagickDraw::translate — 現在の座標系に変換を適用する

### 説明

public function 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();
    }

    ?>

## 目次

- 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 — テキストによる注記を行う際に使用するフォントの伸縮を取得する
- 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 — テキストの行間スペースを取得する
- ImagickDraw::getTextInterwordSpacing — テキストの単語間のスペースを取得する
- ImagickDraw::getTextKerning — テキストのカーニングを取得する
- 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 — ベクターグラフィックをリセットする
- 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 — 解像度を設定する
- 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 — テキストの行間スペースを設定する
- ImagickDraw::setTextInterwordSpacing — テキストの単語間のスペースを設定する
- ImagickDraw::setTextKerning — テキストのカーニングを設定する
- ImagickDraw::setTextUnderColor — 背景の矩形の色を指定する
- ImagickDraw::setVectorGraphics — ベクターグラフィックを設定する
- ImagickDraw::setViewbox — キャンバス全体の大きさを設定する
- ImagickDraw::skewX — 現在の座標系を水平方向に傾ける
- ImagickDraw::skewY — 現在の座標系を垂直方向に傾ける
- ImagickDraw::translate — 現在の座標系に変換を適用する

# The ImagickDrawException class

(PECL imagick 3)

## はじめに

## クラス概要

class ImagickDrawException 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 ImagickException class

(PECL imagick 3)

## はじめに

## クラス概要

class ImagickException 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;
/* メソッド */
/* 継承したメソッド */
}

# ImagickKernel クラス

(PECL imagick >= 3.3.0)

## はじめに

## クラス概要

class ImagickKernel {
/* メソッド */
public function addKernel(ImagickKernel `$ImagickKernel`): void
public function addUnityKernel(float `$scale`): void
public static function fromBuiltin(int `$kernelType`, string `$kernelString`): ImagickKernel
public static function fromMatrix(array `$matrix`, array `$origin` = ?): ImagickKernel
public function getMatrix(): array
public function scale(float `$scale`, int `$normalizeFlag` = ?): void
public function separate(): array
}

# ImagickKernel::addKernel

(PECL imagick >= 3.3.0)

ImagickKernel::addKernel — カーネルリストに別のカーネルを追加する

### 説明

public function ImagickKernel::addKernel(ImagickKernel `$ImagickKernel`): void

このカーネルに別のカーネルを追加し、単一のモルフォロジー関数またはフィルタ関数で 両方を適用できるようにします。結合された新しいカーネルを返します。

### パラメータ

`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();

    }

    ?>

# ImagickKernel::addUnityKernel

(PECL imagick >= 3.3.0)

ImagickKernel::addUnityKernel — カーネルリストに Unity カーネルを追加する

### 説明

public function ImagickKernel::addUnityKernel(float `$scale`): void

事前にスケーリングおよび正規化されたカーネルに、指定した量の 'Unity' 畳み込みカーネルを 追加します。これにより、元の画像がその量だけ畳み込みカーネルの結果に加算されます。 結果として、定義されたカーネルをブレンドされたソフトブラー、 アンシャープカーネル、またはシャープニングカーネルに変換できます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

### 例

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

    }

    ?>

# ImagickKernel::fromBuiltIn

(PECL imagick >= 3.3.0)

ImagickKernel::fromBuiltIn — 組み込みカーネルからカーネルを作成する

### 説明

public static function ImagickKernel::fromBuiltin(int `$kernelType`, string `$kernelString`): ImagickKernel

組み込みカーネルからカーネルを作成します。例については http://www.imagemagick.org/Usage/morphology/#kernel を参照してください。 現時点では 'rotation' シンボルはサポートされていません。例: $diamondKernel = ImagickKernel::fromBuiltIn(\Imagick::KERNEL_DIAMOND, "2");

### パラメータ

`kerneltype`

  作成するカーネルの種類。例: \Imagick::KERNEL_DIAMOND

`kernelString`

  パラメータを記述する文字列。例: "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);

        /* 別レイヤーにドロップシャドウを作成 */
        $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);

        /* 元のテキストレイヤーをシャドウレイヤーに合成 */
        $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);

    ?>

# ImagickKernel::fromMatrix

(PECL imagick >= 3.3.0)

ImagickKernel::fromMatrix — 2次元の値の行列からカーネルを作成する

### 説明

public static function ImagickKernel::fromMatrix(array `$matrix`, array `$origin` = ?): ImagickKernel

2次元の値の行列からカーネルを作成します。各値は float (要素を使用する場合) または 'false' (要素をスキップする場合) のいずれかでなければなりません。 両方の次元が奇数サイズの行列の場合、原点ピクセルはデフォルトでカーネルの 中心になります。その他のすべてのカーネルサイズでは、原点ピクセルを 指定する必要があります。

### パラメータ

`array`

  カーネルを定義する値の行列 (すなわち2次元配列)。各要素は float 値か、 その要素をカーネルで使用しない場合は FALSE でなければなりません。

`array`

  カーネルのどの要素を原点ピクセルとして使用するか。例えば 3x3 の行列で原点を [2, 2] と指定すると、右下の要素が原点ピクセルになります。

### 戻り値

生成された 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);

        /* 別レイヤーにドロップシャドウを作成 */
        $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);

        /* 元のテキストレイヤーをシャドウレイヤーに合成 */
        $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();
    }

    ?>

# ImagickKernel::getMatrix

(PECL imagick >= 3.3.0)

ImagickKernel::getMatrix — カーネルで使用される2次元の値の行列を取得する

### 説明

public function ImagickKernel::getMatrix(): array

カーネルで使用される2次元の値の行列を取得します。各要素は、 使用される要素の場合は float、スキップすべき要素の場合は 'false' です。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

カーネルを表す値の行列（2次元配列）。

### 例

例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;

    ?>

# ImagickKernel::scale

(PECL imagick >= 3.3.0)

ImagickKernel::scale — 指定した量でカーネルリストをスケーリングする

### 説明

public function ImagickKernel::scale(float `$scale`, int `$normalizeFlag` = ?): void

指定したカーネルリストを指定した量でスケーリングします。 カーネル値の合計の正規化あり、またはなし (指定されたフラグに従う) で行います。 この関数の正確な動作は使用される正規化の種類によって異なります。 詳細については http://www.imagemagick.org/api/morphology.php#ScaleKernelInfo を参照してください。

### パラメータ

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

# ImagickKernel::separate

(PECL imagick >= 3.3.0)

ImagickKernel::separate — 連結されたカーネルのセットを分離し、ImagickKernel の配列を返す

### 説明

public function ImagickKernel::separate(): array

連結されたカーネルのセットを分離し、ImagickKernel の配列を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

### 例

例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;

    ?>

## 目次

- ImagickKernel::addKernel — カーネルリストに別のカーネルを追加する
- ImagickKernel::addUnityKernel — カーネルリストに Unity カーネルを追加する
- ImagickKernel::fromBuiltIn — 組み込みカーネルからカーネルを作成する
- ImagickKernel::fromMatrix — 2次元の値の行列からカーネルを作成する
- ImagickKernel::getMatrix — カーネルで使用される2次元の値の行列を取得する
- ImagickKernel::scale — 指定した量でカーネルリストをスケーリングする
- ImagickKernel::separate — 連結されたカーネルのセットを分離し、ImagickKernel の配列を返す

# The ImagickKernelException class

(PECL imagick 3)

## はじめに

## クラス概要

class ImagickKernelException extends Exception {
/* 継承したプロパティ */
protected string $message = "";
private string $string = "";
protected int $code;
protected string $file = "";
protected int $line;
private array $trace = [];
private ?Throwable $previous = null;
/* メソッド */
/* 継承したメソッド */
}

# ImagickPixel クラス

(PECL imagick 2, PECL imagick 3)

## クラス概要

class ImagickPixel {
public function clear(): bool
public function __construct(string `$color` = ?)
public function destroy(): bool
public function getColor(int `$normalized` = 0): array
public function getColorAsString(): string
public function getColorCount(): int
public function getColorQuantum(): array
public function getColorValue(int `$color`): float
public function getColorValueQuantum(int `$color`): int|float
public function getHSL(): array
public function getIndex(): int
public function isPixelSimilar(ImagickPixel `$color`, float `$fuzz`): bool
public function isPixelSimilarQuantum(string `$color`, string `$fuzz` = ?): bool
public function isSimilar(ImagickPixel `$color`, float `$fuzz`): bool
public function setColor(string `$color`): bool
public function setcolorcount(int `$colorCount`): bool
public function setColorValue(int `$color`, float `$value`): bool
public function setColorValueQuantum(int `$color`, int|float `$value`): bool
public function setHSL(float `$hue`, float `$saturation`, float `$luminosity`): bool
public function setIndex(int `$index`): bool
}

# ImagickPixel::clear

(PECL imagick 2, PECL imagick 3)

ImagickPixel::clear — このオブジェクトに関連付けられたリソースを消去する

### 説明

public function ImagickPixel::clear(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ImagickPixel オブジェクトをクリアし、初期状態に戻します。 このオブジェクトに関連付けられている色も初期化します。

### 戻り値

成功した場合に `true` を返します。

# ImagickPixel::__construct

(PECL imagick 2, PECL imagick 3)

ImagickPixel::__construct — ImagickPixel のコンストラクタ

### 説明

public function 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::destroy

(PECL imagick 2, PECL imagick 3)

ImagickPixel::destroy — このオブジェクトに関連付けられているリソースの割り当てを解除する

### 説明

public function ImagickPixel::destroy(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

ImagickPixel オブジェクトが使用しているリソースの割り当てを解除し、 色を初期化します。destroy 関数をコールした後は、このオブジェクトを使用することはできません。

### 戻り値

成功した場合に `true` を返します。

# ImagickPixel::getColor

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getColor — 色を返す

### 説明

public function 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::getColorAsString

(PECL imagick 2 >= 2.1.0, PECL imagick 3)

ImagickPixel::getColorAsString — 色を文字列で返す

### 説明

public function 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::getColorCount

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getColorCount — この色に関連付けられている色カウントを返す

### 説明

public function 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

# ImagickPixel::getColorQuantum

(No version information available, might only be in Git)

ImagickPixel::getColorQuantum — ピクセルの色を quantum 値の配列として返す

### 説明

public function ImagickPixel::getColorQuantum(): array

ピクセルの色を quantum 値の配列として返します。ImageMagick が HDRI 付きでコンパイルされている場合は float、そうでない場合は int になります。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

キー `"r"`、`"g"`、 `"b"`、`"a"` を持つ配列を返します。

# ImagickPixel::getColorValue

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getColorValue — 指定した色チャネルの値を正規化したものを取得する

### 説明

public function 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

# ImagickPixel::getColorValueQuantum

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickPixel::getColorValueQuantum — ImagickPixel の色の quantum 値を取得する

### 説明

public function ImagickPixel::getColorValueQuantum(int `$color`): int|float

ImagickPixel の色の quantum 値を取得します。ImageMagick が HDRI 付きでコンパイルされている場合は float、そうでない場合は int を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

色要素の quantum 値を返します。ImageMagick が HDRI 付きでコンパイルされている場合は float、そうでない場合は 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::getHSL

(PECL imagick 2, PECL imagick 3)

ImagickPixel::getHSL — ImagickPixel オブジェクトの HSL カラーを正規化したものを返す

### 説明

public function 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 以降で使用可能です。

# ImagickPixel::getIndex

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickPixel::getIndex — pixel wand のカラーマップインデックスを取得する

### 説明

public function ImagickPixel::getIndex(): int

pixel wand のカラーマップインデックスを取得します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

# ImagickPixel::isPixelSimilar

(PECL imagick 3 >= 3.3.0)

ImagickPixel::isPixelSimilar — この色と別の色の差を調べる

### 説明

public function ImagickPixel::isPixelSimilar(ImagickPixel `$color`, float `$fuzz`): bool

この ImagickPixel オブジェクトと指定されたオブジェクトの色の差を調べます。 これは、両者の RGB 値を色立方体上にプロットすることで行います。 ふたつの色の差が fuzz で指定した値よりも小さければ、 同じ色であるとみなされます。 このメソッドは ImagickPixel::isSimilar() を置き換えるもので、fuzz 値を ImageMagick の QuantumRange に正しく正規化します。

### パラメータ

`color`

  このオブジェクトと比較したい ImagickPixel オブジェクト。

`fuzz`

  同じ色であるとみなす最大の誤差。 理論上の最大値は、3 の平方根 (1.732) となります。

### 戻り値

成功した場合に `true` を返します。

# ImagickPixel::isPixelSimilarQuantum

(PECL imagick 3 >= 3.3.0)

ImagickPixel::isPixelSimilarQuantum — ふたつの色の差が指定した距離未満かどうかを返す

### 説明

public function ImagickPixel::isPixelSimilarQuantum(string `$color`, string `$fuzz` = ?): bool

ふたつの色の差が指定した距離未満の場合に true を返します。 fuzz の値は 0 から QuantumRange の範囲で指定します。 最大値は、色空間上で取り得る最長距離を表します。 たとえば RGB 色空間では RGB(0, 0, 0) から RGB(255, 255, 255) までの距離です。

### パラメータ

`color`

`fuzz`

### 戻り値

# ImagickPixel::isSimilar

(PECL imagick 2, PECL imagick 3)

ImagickPixel::isSimilar — この色と別の色の差を調べる

### 説明

public function 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::setColor

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setColor — 色を設定する

### 説明

public function 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();
    }

    ?>

# ImagickPixel::setColorCount

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setColorCount — この色に関連付けられている色カウントを設定する

### 説明

public function ImagickPixel::setcolorcount(int `$colorCount`): bool

この色に関連付けられている色カウントを設定します。

### パラメータ

`colorCount`

### 戻り値

成功した場合に `true` を返します。

# ImagickPixel::setColorValue

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setColorValue — 指定したチャネルの正規化した値を設定する

### 説明

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

# ImagickPixel::setColorValueQuantum

(PECL imagick 2 >=2.3.0, PECL imagick 3)

ImagickPixel::setColorValueQuantum — ImagickPixel の色要素の quantum 値を設定する

### 説明

public function ImagickPixel::setColorValueQuantum(int `$color`, int|float `$value`): bool

ImagickPixel の色要素の quantum 値を設定します。

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`color`

  設定する色要素。\Imagick::COLOR_GREEN など。

`value`

  色要素に設定する quantum 値。ImageMagick が HDRI 付きでコンパイルされている場合は float、そうでない場合は 0 から Imagick::getQuantum() の範囲の int を指定します。

### 戻り値

成功した場合に `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();
    }

    ?>

# ImagickPixel::setHSL

(PECL imagick 2, PECL imagick 3)

ImagickPixel::setHSL — 正規化した HSL カラーを設定する

### 説明

public function 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 以降で使用可能です。

# ImagickPixel::setIndex

(PECL imagick 2 >= 2.3.0, PECL imagick 3)

ImagickPixel::setIndex — pixel wand のカラーマップインデックスを設定する

### 説明

public function ImagickPixel::setIndex(int `$index`): bool

pixel wand のカラーマップインデックスを設定します。

### パラメータ

`index`

### 戻り値

成功した場合に `true` を返します。

## 目次

- ImagickPixel::clear — このオブジェクトに関連付けられたリソースを消去する
- ImagickPixel::__construct — ImagickPixel のコンストラクタ
- ImagickPixel::destroy — このオブジェクトに関連付けられているリソースの割り当てを解除する
- ImagickPixel::getColor — 色を返す
- ImagickPixel::getColorAsString — 色を文字列で返す
- ImagickPixel::getColorCount — この色に関連付けられている色カウントを返す
- ImagickPixel::getColorQuantum — ピクセルの色を quantum 値の配列として返す
- ImagickPixel::getColorValue — 指定した色チャネルの値を正規化したものを取得する
- ImagickPixel::getColorValueQuantum — ImagickPixel の色の quantum 値を取得する
- ImagickPixel::getHSL — ImagickPixel オブジェクトの HSL カラーを正規化したものを返す
- ImagickPixel::getIndex — pixel wand のカラーマップインデックスを取得する
- ImagickPixel::isPixelSimilar — この色と別の色の差を調べる
- ImagickPixel::isPixelSimilarQuantum — ふたつの色の差が指定した距離未満かどうかを返す
- ImagickPixel::isSimilar — この色と別の色の差を調べる
- ImagickPixel::setColor — 色を設定する
- ImagickPixel::setColorCount — この色に関連付けられている色カウントを設定する
- ImagickPixel::setColorValue — 指定したチャネルの正規化した値を設定する
- ImagickPixel::setColorValueQuantum — ImagickPixel の色要素の quantum 値を設定する
- ImagickPixel::setHSL — 正規化した HSL カラーを設定する
- ImagickPixel::setIndex — pixel wand のカラーマップインデックスを設定する

# The ImagickPixelException class

(PECL imagick 3)

## はじめに

## クラス概要

class ImagickPixelException 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;
/* メソッド */
/* 継承したメソッド */
}

# ImagickPixelIterator クラス

(PECL imagick 2, PECL imagick 3)

## クラス概要

class ImagickPixelIterator {
public function clear(): bool
public function __construct(Imagick `$wand`)
public function destroy(): bool
public function getCurrentIteratorRow(): array
public function getIteratorRow(): int
public function getNextIteratorRow(): array
public function getPreviousIteratorRow(): array
public function newPixelIterator(Imagick `$wand`): bool
public function newPixelRegionIterator(
Imagick `$wand`,
int `$x`,
int `$y`,
int `$columns`,
int `$rows`
): bool
public function resetIterator(): bool
public function setIteratorFirstRow(): bool
public function setIteratorLastRow(): bool
public function setIteratorRow(int `$row`): bool
public function syncIterator(): bool
}

# ImagickPixelIterator::clear

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::clear — PixelIterator に関連付けられたリソースを消去する

### 説明

public function 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::__construct

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::__construct — ImagickPixelIterator のコンストラクタ

### 説明

public function 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;
    }

    ?>

# ImagickPixelIterator::destroy

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::destroy — PixelIterator に関連付けられているリソースの割り当てを解除する

### 説明

public function ImagickPixelIterator::destroy(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

PixelIterator に関連付けられているリソースの割り当てを解除します。

### 戻り値

成功した場合に `true` を返します。

# ImagickPixelIterator::getCurrentIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getCurrentIteratorRow — ImagickPixel オブジェクトの現在の行を返す

### 説明

public function ImagickPixelIterator::getCurrentIteratorRow(): array
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

pixel iterator の現在の行を、ImagickPixel オブジェクトの配列で返します。

### 戻り値

ImagickPixel オブジェクトの配列形式で行を返します。これを順次処理することが可能です。

# ImagickPixelIterator::getIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getIteratorRow — pixel iterator の現在の行を返す

### 説明

public function ImagickPixelIterator::getIteratorRow(): int
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

pixel iterator の現在の行を返します。

### 戻り値

pixel iterator の現在の行を返します。 エラー時には ImagickPixelIteratorException をスローします。

# ImagickPixelIterator::getNextIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getNextIteratorRow — pixel iterator の次の行を返す

### 説明

public function 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::getPreviousIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::getPreviousIteratorRow — 前の行を返す

### 説明

public function ImagickPixelIterator::getPreviousIteratorRow(): array
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

pixel iterator の前の行を、pixel wands の配列として返します。

### 戻り値

ImagickPixelIterator の前の行を、ImagickPixelWand オブジェクトの配列として返します。エラー時には ImagickPixelIteratorException をスローします。

# ImagickPixelIterator::newPixelIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::newPixelIterator — 新しい pixel iterator を返す

### 説明

public function ImagickPixelIterator::newPixelIterator(Imagick `$wand`): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

新しい pixel iterator を返します。

### 戻り値

成功した場合に `true` を返します。 ImagickPixelIteratorException をスローします。

# ImagickPixelIterator::newPixelRegionIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::newPixelRegionIterator — 新しい pixel iterator を返す

### 説明

public function ImagickPixelIterator::newPixelRegionIterator(
Imagick `$wand`,
int `$x`,
int `$y`,
int `$columns`,
int `$rows`
): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

新しい pixel iterator を返します。

### パラメータ

`wand`

`x`

`y`

`columns`

`rows`

### 戻り値

成功した場合に新しい ImagickPixelIterator を返します。 失敗した場合は ImagickPixelIteratorException をスローします。

# ImagickPixelIterator::resetIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::resetIterator — pixel iterator をリセットする

### 説明

public function 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;
    }

    ?>

# ImagickPixelIterator::setIteratorFirstRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::setIteratorFirstRow — pixel iterator を最初の行に設定する

### 説明

public function ImagickPixelIterator::setIteratorFirstRow(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

pixel iterator を最初の行に設定します。

### 戻り値

成功した場合に `true` を返します。

# ImagickPixelIterator::setIteratorLastRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::setIteratorLastRow — pixel iterator を最後の行に設定する

### 説明

public function ImagickPixelIterator::setIteratorLastRow(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

pixel iterator を最後の行に設定します。

### 戻り値

成功した場合に `true` を返します。

# ImagickPixelIterator::setIteratorRow

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::setIteratorRow — pixel iterator の行を設定する

### 説明

public function 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;
    }

    ?>

# ImagickPixelIterator::syncIterator

(PECL imagick 2, PECL imagick 3)

ImagickPixelIterator::syncIterator — pixel iterator を同期する

### 説明

public function ImagickPixelIterator::syncIterator(): bool
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

pixel iterator を同期します。

### 戻り値

成功した場合に `true` を返します。

## 目次

- 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 を同期する

# The ImagickPixelIteratorException class

(PECL imagick 3)

## はじめに

## クラス概要

class ImagickPixelIteratorException 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;
/* メソッド */
/* 継承したメソッド */
}

- インストール/設定
  - 要件
  - インストール手順
  - 実行時設定
- 定義済み定数
- 例
  - 基本的な使用法
- 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 — 特定の画像チャネルのレベルを調整する
  - Imagick::averageImages — 画像群を平均化する
  - Imagick::blackThresholdImage — 閾値に満たないすべてのピクセルを黒にする
  - Imagick::blueShiftImage — 画像の色を落ち着かせる
  - Imagick::blurImage — blur (にじみ) フィルタを画像に追加する
  - Imagick::borderImage — 画像の周りを枠線で囲む
  - Imagick::brightnessContrastImage — 画像の明るさやコントラストを変更する
  - Imagick::charcoalImage — 木炭画をシミュレートする
  - Imagick::chopImage — 画像の一部を取り除き、切り詰める
  - Imagick::clampImage — 色の範囲を 0 から quantum depth までに制限する
  - Imagick::clear — Imagick オブジェクトに関連付けられたすべてのリソースをクリアする
  - Imagick::clipImage — 8BIM プロファイルの最初のパスにそって切り取る
  - Imagick::clipImagePath — 8BIM プロファイルの名前付きパスがあればそれに沿ってクリップする
  - Imagick::clipPathImage — 8BIM プロファイルの指定した名前のパスにそって切り取る
  - Imagick::clone — Imagick オブジェクトの完全なコピーを作成する
  - Imagick::clutImage — 画像の色を置き換える
  - Imagick::coalesceImages — 複数の画像を合成する
  - Imagick::colorFloodfillImage — 対象にマッチする任意の点の色の値を変更する
  - Imagick::colorizeImage — 塗りつぶし色と画像を混合する
  - Imagick::colorMatrixImage — 画像に色変換を適用する
  - Imagick::combineImages — ひとつあるいは複数の画像をひとつにまとめる
  - Imagick::commentImage — コメントを画像に追加する
  - Imagick::compareImageChannels — ひとつあるいは複数の画像の差を返す
  - Imagick::compareImageLayers — 複数の画像の中で最大の境界範囲を返す
  - Imagick::compareImages — ある画像を再構築された画像と比較する
  - Imagick::compositeImage — ある画像を別の画像に合成する
  - Imagick::__construct — Imagick のコンストラクタ
  - Imagick::contrastImage — 画像のコントラストを変更する
  - Imagick::contrastStretchImage — カラー画像のコントラストを強調する
  - Imagick::convolveImage — 独自の畳み込み関数を画像に適用する
  - Imagick::count — 画像の数を取得する
  - Imagick::cropImage — 画像の一部を抽出する
  - Imagick::cropThumbnailImage — 切り取ってサムネイルを作成する
  - Imagick::current — 現在の Imagick オブジェクトへの参照を返す
  - Imagick::cycleColormapImage — 画像のカラーマップを移動する
  - Imagick::decipherImage — 画像を復号する
  - Imagick::deconstructImages — 画像間の特定のピクセルの差を返す
  - Imagick::deleteImageArtifact — 画像のアーチファクトを削除する
  - Imagick::deleteImageProperty — 画像のプロパティを削除する
  - 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 — カスタム畳み込みカーネルを画像に適用する
  - Imagick::flattenImages — 画像シーケンスをマージする
  - Imagick::flipImage — 垂直方向に反転した画像を作成する
  - Imagick::floodFillPaintImage — 対象にマッチする任意のピクセルの値を変更する
  - Imagick::flopImage — 水平方向に反転した画像を作成する
  - Imagick::forwardFourierTransformImage — 離散フーリエ変換 (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 — 名前を指定して属性を返す
  - 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 — 画像の MIME タイプを返す
  - 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 — ImageMagick の quantum range を返す
  - Imagick::getQuantumDepth — quantum depth を取得する
  - Imagick::getQuantumRange — Imagick quantum range を返す
  - Imagick::getRegistry — StringRegistry エントリを取得する
  - Imagick::getReleaseDate — ImageMagick のリリース日を返す
  - Imagick::getResource — 指定したリソースのメモリ使用状況を返す
  - Imagick::getResourceLimit — 指定したリソースの制限を返す
  - Imagick::getSamplingFactors — 水平方向および垂直方向のサンプリング係数を取得する
  - Imagick::getSize — Imagick オブジェクトに関連付けられたサイズを返す
  - Imagick::getSizeOffset — サイズのオフセットを返す
  - Imagick::getVersion — ImageMagick API のバージョンを返す
  - Imagick::haldClutImage — 画像内の色を置換する
  - Imagick::hasNextImage — オブジェクトが次の画像を保持しているかどうかを調べる
  - Imagick::hasPreviousImage — オブジェクトが前の画像を保持しているかどうかを調べる
  - Imagick::identifyFormat — 画像の詳細情報で文字列をフォーマットする
  - Imagick::identifyImage — 画像を識別し、属性を取得する
  - Imagick::implodeImage — 新しい画像をコピーとして作成する
  - Imagick::importImagePixels — 画像のピクセルをインポートする
  - Imagick::inverseFourierTransformImage — 逆離散フーリエ変換 (DFT) を実行する
  - Imagick::labelImage — ラベルを画像に追加する
  - Imagick::levelImage — 画像のレベルを調節する
  - Imagick::linearStretchImage — 画像の輝度を引き伸ばして飽和させる
  - Imagick::liquidRescaleImage — 画像を動かす
  - Imagick::listRegistry — すべてのレジストリ設定を一覧表示する
  - Imagick::magnifyImage — 画像を 2 倍に比例拡大する
  - Imagick::mapImage — 画像の色を、参照画像の中の最も近い色に置き換える
  - Imagick::matteFloodfillImage — 色の透明度を変更する
  - Imagick::medianFilterImage — デジタルフィルタを適用する
  - Imagick::mergeImageLayers — 画像のレイヤーをマージする
  - Imagick::minifyImage — 画像をその半分のサイズに比例縮小する
  - Imagick::modulateImage — 明度、飽和度、色相を制御する
  - Imagick::montageImage — 合成画像を作成する
  - Imagick::morphImages — 複数の画像をモーフィングする
  - Imagick::morphology — 指定されたモルフォロジーメソッドに従い、ユーザー指定のカーネルを画像に適用する
  - 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 — ファイル名の配列から画像を読み込む
  - Imagick::recolorImage — 画像の色を変更する
  - Imagick::reduceNoiseImage — 画像の輪郭をなめらかにする
  - Imagick::remapImage — 画像の色を再配置する
  - Imagick::removeImage — 画像リストから画像を削除する
  - Imagick::removeImageProfile — 指定した名前の画像プロファイルを削除してそれを返す
  - Imagick::render — それまでのすべての描画コマンドをレンダリングする
  - Imagick::resampleImage — 画像を指定した解像度にリサンプリングする
  - Imagick::resetImagePage — 画像のページをリセットする
  - Imagick::resizeImage — 画像のサイズを変更する
  - Imagick::rollImage — 画像を補正する
  - Imagick::rotateImage — 画像を回転する
  - Imagick::rotationalBlurImage — 画像に回転ブラーを施す
  - Imagick::roundCorners — 画像の角を丸める
  - Imagick::sampleImage — ピクセルのサンプリングによって画像の倍率を変更する
  - Imagick::scaleImage — 画像のサイズを変更する
  - Imagick::segmentImage — 画像を分割する
  - Imagick::selectiveBlurImage — コントラストの閾値内で選択的に画像をぼかす
  - 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 — 画像の属性を設定する
  - Imagick::setImageBackgroundColor — 画像の背景色を設定する
  - Imagick::setImageBias — 画像を折りたたむ任意のメソッドについて画像のバイアスを設定する
  - Imagick::setImageBiasQuantum — 画像のバイアスを設定する
  - 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 — 処理中に呼び出されるコールバックを設定する
  - Imagick::setRegistry — 指定されたキーの ImageMagick レジストリエントリに値を設定する
  - 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 — 現在の画像ポインタから画像リストの最後までのすべての画像を取得し、結合する
  - Imagick::solarizeImage — 画像にソラリゼーション効果を適用する
  - Imagick::sparseColorImage — 色を補間する
  - Imagick::spliceImage — 無地の画像を作成する
  - Imagick::spreadImage — ブロック内の各ピクセルをランダムに移動する
  - Imagick::statisticImage — 統計関数を使用して画像を変更する
  - Imagick::steganoImage — デジタル透かしを画像に埋め込む
  - Imagick::stereoImage — ふたつの画像を合成する
  - Imagick::stripImage — 画像からすべてのプロパティやコメントを除去する
  - Imagick::subImageMatch — 現在の画像から部分画像を検索し、類似度画像を返す
  - Imagick::swirlImage — 画像の中心から、ピクセルを渦巻状にする
  - Imagick::textureImage — テクスチャ画像をタイル状に並べる
  - Imagick::thresholdImage — 閾値にもとづいて個々のピクセルの値を変更する
  - Imagick::thumbnailImage — 画像のサイズを変更する
  - Imagick::tintImage — 色ベクトルを画像の各ピクセルに適用する
  - Imagick::__toString — 画像を文字列として返す
  - Imagick::transformImage — 切り取るサイズと画像のジオメトリを設定する便利なメソッド
  - Imagick::transformImageColorspace — 画像を新しい色空間に変換する
  - 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 — テキストによる注記を行う際に使用するフォントの伸縮を取得する
  - 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 — テキストの行間スペースを取得する
  - ImagickDraw::getTextInterwordSpacing — テキストの単語間のスペースを取得する
  - ImagickDraw::getTextKerning — テキストのカーニングを取得する
  - 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 — ベクターグラフィックをリセットする
  - 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 — 解像度を設定する
  - 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 — テキストの行間スペースを設定する
  - ImagickDraw::setTextInterwordSpacing — テキストの単語間のスペースを設定する
  - ImagickDraw::setTextKerning — テキストのカーニングを設定する
  - ImagickDraw::setTextUnderColor — 背景の矩形の色を指定する
  - ImagickDraw::setVectorGraphics — ベクターグラフィックを設定する
  - ImagickDraw::setViewbox — キャンバス全体の大きさを設定する
  - ImagickDraw::skewX — 現在の座標系を水平方向に傾ける
  - ImagickDraw::skewY — 現在の座標系を垂直方向に傾ける
  - ImagickDraw::translate — 現在の座標系に変換を適用する
- ImagickDrawException — The ImagickDrawException class
- ImagickException — The ImagickException class
- ImagickKernel — ImagickKernel クラス
  - ImagickKernel::addKernel — カーネルリストに別のカーネルを追加する
  - ImagickKernel::addUnityKernel — カーネルリストに Unity カーネルを追加する
  - ImagickKernel::fromBuiltIn — 組み込みカーネルからカーネルを作成する
  - ImagickKernel::fromMatrix — 2次元の値の行列からカーネルを作成する
  - ImagickKernel::getMatrix — カーネルで使用される2次元の値の行列を取得する
  - ImagickKernel::scale — 指定した量でカーネルリストをスケーリングする
  - ImagickKernel::separate — 連結されたカーネルのセットを分離し、ImagickKernel の配列を返す
- ImagickKernelException — The ImagickKernelException class
- ImagickPixel — ImagickPixel クラス
  - ImagickPixel::clear — このオブジェクトに関連付けられたリソースを消去する
  - ImagickPixel::__construct — ImagickPixel のコンストラクタ
  - ImagickPixel::destroy — このオブジェクトに関連付けられているリソースの割り当てを解除する
  - ImagickPixel::getColor — 色を返す
  - ImagickPixel::getColorAsString — 色を文字列で返す
  - ImagickPixel::getColorCount — この色に関連付けられている色カウントを返す
  - ImagickPixel::getColorQuantum — ピクセルの色を quantum 値の配列として返す
  - ImagickPixel::getColorValue — 指定した色チャネルの値を正規化したものを取得する
  - ImagickPixel::getColorValueQuantum — ImagickPixel の色の quantum 値を取得する
  - ImagickPixel::getHSL — ImagickPixel オブジェクトの HSL カラーを正規化したものを返す
  - ImagickPixel::getIndex — pixel wand のカラーマップインデックスを取得する
  - ImagickPixel::isPixelSimilar — この色と別の色の差を調べる
  - ImagickPixel::isPixelSimilarQuantum — ふたつの色の差が指定した距離未満かどうかを返す
  - ImagickPixel::isSimilar — この色と別の色の差を調べる
  - ImagickPixel::setColor — 色を設定する
  - ImagickPixel::setColorCount — この色に関連付けられている色カウントを設定する
  - ImagickPixel::setColorValue — 指定したチャネルの正規化した値を設定する
  - ImagickPixel::setColorValueQuantum — ImagickPixel の色要素の quantum 値を設定する
  - ImagickPixel::setHSL — 正規化した HSL カラーを設定する
  - ImagickPixel::setIndex — pixel wand のカラーマップインデックスを設定する
- ImagickPixelException — The ImagickPixelException class
- 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 を同期する
- ImagickPixelIteratorException — The ImagickPixelIteratorException class

- 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 クラス
  - ImagickDrawException — The ImagickDrawException class
  - ImagickException — The ImagickException class
  - ImagickKernel — ImagickKernel クラス
  - ImagickKernelException — The ImagickKernelException class
  - ImagickPixel — ImagickPixel クラス
  - ImagickPixelException — The ImagickPixelException class
  - ImagickPixelIterator — ImagickPixelIterator クラス
  - ImagickPixelIteratorException — The ImagickPixelIteratorException class

# メール関連

# IMAP、POP3 および NNTP

# はじめに

警告

この拡張モジュールは、PHP 8.4.0 以降では非推奨となり、PHP にもバンドルされません。

これらの関数は、IMAP プロトコルのほかに NNTP や POP3、 そしてローカルのメールボックスへのアクセスもサポートします。

しかし、IMAP 関数の中には POP プロトコルでは正常に動作しないものがあることに注意しましょう。

警告

IMAP 拡張モジュールはスレッドセーフではありません。 よって、ZTS が有効なPHPで使うべきではありません。

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定
- リソース型

## 要件

この拡張モジュールを使うには、 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 サポートを使用するには、これらの ライブラリを再コンパイルする必要があります。

## インストール手順

## PHP 8.4

この拡張モジュールは » PECL レポジトリに移動 されており、以下のバージョン以降 PHP にバンドルされなくなっています。 PHP 8.4.0

この PECL 拡張モジュールをインストールする方法は、 マニュアルの PECL 拡張モジュールのインストール という章にあります。 新規リリース・ダウンロード・ソースファイル・管理者情報・CHANGELOG といった関連する情報については、次の場所にあります。 » https://pecl.php.net/package/imap.

## PHP < 8.4

これらの関数を動作させるには、--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

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_8bit — 8 ビット文字列を quoted-printable 文字列に変換する

### 説明

function imap_8bit(string `$string`): string|false

(» RFC2045, section 6.7 に基づき) 8 ビット文字列を quoted-printable 文字列に変換します。

### パラメータ

`string`

  変換する 8 ビット文字列。

### 戻り値

quoted-printable 文字列を返します。 失敗した場合に `false` を返します

### 参考

- imap_qprint() - quoted-printable 文字列を 8 ビット文字列に変換する

# imap_alerts

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_alerts — 発生した IMAP 警告メッセージを返す

### 説明

function imap_alerts(): array|false

直近に imap_alerts() をコールして以来、 またはページ処理を開始して以来生成された 全 IMAP 警告メッセージの配列を返します。

imap_alerts() がコールされた場合、 その処理後に警告のスタックはクリアされます。IMAP の仕様では、 これらのメッセージをユーザーに渡すことが規定されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

全ての IMAP 警告メッセージの配列、あるいは警告メッセージが発生していない場合は `false` を返します。

### 参考

- imap_errors() - 発生したすべての IMAP エラーを返す

# imap_append

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_append — 指定されたメールボックスに文字列メッセージを追加する

### 説明

function 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` resource が期待されていました。
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);
    ?>

# imap_base64

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_base64 — BASE64 でエンコードされたテキストをデコードする

### 説明

function 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

# imap_binary

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_binary — 8 ビット文字列を base64 文字列に変換する

### 説明

function imap_binary(string `$string`): string|false

（» RFC2045, Section 6.8 に基づき）8 ビット文字列を base64 文字列に変換します。

### パラメータ

`string`

  8 ビット文字列。

### 戻り値

base64 エンコードされた文字列を返します。 失敗した場合に `false` を返します

### 参考

- imap_base64() - BASE64 でエンコードされたテキストをデコードする

# imap_body

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_body — メッセージ本文を読む

### 説明

function 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` resource が期待されていました。

# imap_bodystruct

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_bodystruct — 指定したメッセージの指定した body セクションの構造を読み込む

### 説明

function 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` resource が期待されていました。

### 参考

- imap_fetchstructure() - 特定のメッセージの構造を読み込む

# imap_check

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_check — 現在のメールボックスをチェックする

### 説明

function 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` resource が期待されていました。

### 例

例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_clearflag_full

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_clearflag_full — メッセージのフラグをクリアする

### 説明

function 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` resource が期待されていました。
8.0.0 | `options` が無効な値の場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、 警告が発生し、`false` を返していました。

### 参考

- imap_setflag_full() - メッセージにフラグをセットする

# imap_close

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_close — IMAP ストリームをクローズする

### 説明

function 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` resource が期待されていました。
8.0.0 | `flags` が無効な値の場合、 ValueError がスローされるようになりました。 これより前のバージョンでは、 警告が発生し、`false` を返していました。

### 参考

- imap_open() - メールボックスへの IMAP ストリームをオープンする

# imap_create

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_create — imap_createmailbox() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 imap_createmailbox().

# imap_createmailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_createmailbox — 新しいメールボックスを作る

### 説明

function 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` resource が期待されていました。

### 例

例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("phpnewböx"); // 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_delete

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_delete — 現在のメールボックスから削除するメッセージに印を付ける

### 説明

function 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` resource が期待されていました。
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_deletemailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_deletemailbox — メールボックスを削除する

### 説明

function 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` resource が期待されていました。

### 参考

- imap_createmailbox() - 新しいメールボックスを作る
- imap_renamemailbox() - メールボックスの名前を変更する
- `mbox` の書式については imap_open() - メールボックスへの IMAP ストリームをオープンする

# imap_errors

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_errors — 発生したすべての IMAP エラーを返す

### 説明

function imap_errors(): array|false

ページのリクエストの間かエラースタックがリセットされて以来 生じた全ての IMAP エラー (存在すれば) を返します。

imap_errors() がコールされると、 処理の終了後にエラースタックがクリアされます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

この関数は、最後に imap_errors() コールを行ってから、またはそのページの処理を開始してから 発生した全ての IMAP エラーメッセージの配列を返します。 エラーメッセージが存在しない場合には `false` を返します。

### 参考

- imap_last_error() - ページリクエスト時に生じた直近の IMAP エラーを返す
- imap_alerts() - 発生した IMAP 警告メッセージを返す

# imap_expunge

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_expunge — 削除用にマークされたすべてのメッセージを削除する

### 説明

function 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` resource が期待されていました。

# imap_fetch_overview

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetch_overview — 指定したメッセージのヘッダ情報の概要を読む

### 説明

function 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` resource が期待されていました。

### 例

例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_fetchbody

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchbody — メッセージ本文中の特定のセクションを取り出す

### 説明

function 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` resource が期待されていました。

### 参考

- imap_savebody() - 指定した本文部をファイルに保存する
- imap_fetchstructure() - 特定のメッセージの構造を読み込む

# imap_fetchheader

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchheader — メッセージのヘッダを返す

### 説明

function 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` resource が期待されていました。

### 参考

- imap_fetch_overview() - 指定したメッセージのヘッダ情報の概要を読む

# imap_fetchmime

(PHP 5 >= 5.3.6, PHP 7, PHP 8)

imap_fetchmime — メッセージの特定のセクションに対する MIME ヘッダを取り出します

### 説明

function 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` resource が期待されていました。

### 参考

- imap_fetchbody() - メッセージ本文中の特定のセクションを取り出す
- imap_fetchstructure() - 特定のメッセージの構造を読み込む
- imap_fetchheader() - メッセージのヘッダを返す

# imap_fetchstructure

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchstructure — 特定のメッセージの構造を読み込む

### 説明

function 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` resource が期待されていました。

### 参考

- imap_fetchbody() - メッセージ本文中の特定のセクションを取り出す
- imap_bodystruct() - 指定したメッセージの指定した body セクションの構造を読み込む

# imap_fetchtext

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_fetchtext — imap_body() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 imap_body().

# imap_gc

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

imap_gc — IMAP キャッシュをクリアする

### 説明

function 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` resource が期待されていました。
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_get_quota

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

imap_get_quota — クオータレベルの設定、メールボックス毎の使用状況を取得する

### 説明

function 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` resource が期待されていました。

### 例

例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_quotaroot

(PHP 4 >= 4.3.0, PHP 5, PHP 7, PHP 8)

imap_get_quotaroot — ユーザー単位のクォータ設定を取得する

### 説明

function 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` resource が期待されていました。

### 例

例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() - クオータレベルの設定、メールボックス毎の使用状況を取得する

# imap_getacl

(PHP 5, PHP 7, PHP 8)

imap_getacl — 与えられたメールボックスの ACL を取得する

### 説明

function 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` resource が期待されていました。

### 例

例1 imap_getacl() の例

    <?php

    print_r(imap_getacl($imap, 'user.joecool'));

    ?>

上の例の出力は、 たとえば以下のようになります。

    Array
    (
        [asubfolder] => lrswipcda
        [anothersubfolder] => lrswipcda
    )

### 注意

この関数は、現在は c-client2000 以降のライブラリを使用しているユーザーのみ利用可能です。

### 参考

- imap_setacl() - 指定したメールボックスの ACL を設定する

# imap_getmailboxes

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_getmailboxes — メールボックスのリストを読み込み、各ボックスに関する詳細な情報を返す

### 説明

function 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` resource が期待されていました。

### 例

例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_getsubscribed

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_getsubscribed — 購読中の全メールボックスの一覧を取得する

### 説明

function 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` resource が期待されていました。

# imap_header

(PHP 4, PHP 5, PHP 7)

imap_header — imap_headerinfo() のエイリアス

警告

このエイリアスは PHP 8.0.0 で 削除 されました。

### 説明

この関数は次の関数のエイリアスです。 imap_headerinfo().

# imap_headerinfo

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_headerinfo — メッセージヘッダを読み込む

### 説明

function 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` プロパティの文字数。 ゼロ以上でなければなりません。

### 戻り値

エラー時には `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` resource が期待されていました。
8.0.0 | 未使用だった `defaulthost` が削除されました。

### 参考

- imap_fetch_overview() - 指定したメッセージのヘッダ情報の概要を読む

# imap_headers

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_headers — メールボックス内のすべてのメッセージのヘッダを返す

### 説明

function imap_headers(IMAP\Connection `$imap`): array|false

メールボックス内のすべてのメッセージのヘッダを返します。

### パラメータ

`imap`
  IMAP\Connection クラスのインスタンス。

### 戻り値

ヘッダ情報でフォーマットされた文字列の配列を返します。1 つの メールメッセージ毎に 1 つの要素が格納されます。 失敗した場合に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | 引数 `imap` は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な `imap` resource が期待されていました。

# imap_is_open

(PHP 8 >= 8.2.1)

imap_is_open — IMAP ストリームがまだ有効かを調べる

### 説明

function 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_last_error

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_last_error — ページリクエスト時に生じた直近の IMAP エラーを返す

### 説明

function imap_last_error(): string|false

現在のページに生じた直近の IMAP エラーメッセージの全文を返します。 エラースタックは変更されません。 imap_last_error() を続けてコールした際、 コール間に新規エラーが生じていない場合は同じエラーが返されます。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

現在のページに生じた直近の IMAP エラーメッセージの全文を返します。 エラーメッセージが存在しない場合は `false` を返します。

### 参考

- imap_errors() - 発生したすべての IMAP エラーを返す

# imap_list

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_list — メールボックスのリストを読み込む

### 説明

function 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` resource が期待されていました。

### 例

例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_listmailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_listmailbox — imap_list() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 imap_list().

# imap_listscan

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_listscan — 指定したテキストにマッチするメールボックスの一覧を返す

### 説明

function 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` resource が期待されていました。

### 参考

- imap_listmailbox() - imap_list のエイリアス
- imap_search() - 指定した検索条件にマッチするメッセージを配列として返す

# imap_listsubscribed

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_listsubscribed — imap_lsub() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 imap_lsub().

# imap_lsub

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_lsub — 購読しているすべてのメールボックスの一覧を得る

### 説明

function 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` resource が期待されていました。

### 参考

- imap_list() - メールボックスのリストを読み込む
- imap_getmailboxes() - メールボックスのリストを読み込み、各ボックスに関する詳細な情報を返す

# imap_mail

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail — e-mail メッセージを送信する

### 説明

function 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 メッセージを作成する

# imap_mail_compose

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail_compose — 指定したエンベロープおよびボディセクションに基づいて MIME メッセージを作成する

### 説明

function 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_copy

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail_copy — 指定されたメッセージをメールボックスにコピーする

### 説明

function 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` resource が期待されていました。

### 参考

- imap_mail_move() - 指定されたメッセージをメールボックスに移動する

# imap_mail_move

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mail_move — 指定されたメッセージをメールボックスに移動する

### 説明

function 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` resource が期待されていました。

### 注意

> 注意:

> imap_mail_move() は元のメールに削除フラグを立てます。 imap_expunge() がコールされたときに確実に削除されるようにするためです。

### 参考

- imap_mail_copy() - 指定されたメッセージをメールボックスにコピーする

# imap_mailboxmsginfo

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mailboxmsginfo — 現在のメールボックスに関する情報を得る

### 説明

function 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` resource が期待されていました。

### 例

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

    ?>

# imap_mime_header_decode

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_mime_header_decode — MIME ヘッダ要素をデコードする

### 説明

function 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 Jørn Simonsen

    Charset: default
    Text:  <keld@example.com>

上の例には二つの要素があります。最初の要素は ISO-8859-1、 2 番目の要素はプレーンな US-ASCII で事前にエンコードされています。

### 参考

- imap_utf8() - MIME エンコードされたテキストを UTF-8 に変換する

# imap_msgno

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_msgno — 指定した UID のメッセージ番号を返す

### 説明

function 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` resource が期待されていました。

### 参考

- imap_uid() - 指定したメッセージシーケンス番号の UID を返す

# imap_mutf7_to_utf8

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

imap_mutf7_to_utf8 — 修正UTF-7文字列をUTF-8にデコードする

### 説明

function 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_num_msg

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_num_msg — 現在のメールボックスのメッセージ数を取得する

### 説明

function imap_num_msg(IMAP\Connection `$imap`): int|false

現在のメールボックスにあるメッセージ数を返します。

### パラメータ

`imap`
  IMAP\Connection クラスのインスタンス。

### 戻り値

現在のメールボックスのメッセージ数を整数として返します。 またはエラー時に `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | 引数 `imap` は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な `imap` resource が期待されていました。

### 参考

- imap_num_recent() - 現在のメールボックスにある新規メッセージ数を取得する
- imap_status() - 現在のメールボックス以外のメールボックスのステータス情報を返す

# imap_num_recent

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_num_recent — 現在のメールボックスにある新規メッセージ数を取得する

### 説明

function imap_num_recent(IMAP\Connection `$imap`): int

現在のメールボックスにある新しいメッセージの数を返します。

### パラメータ

`imap`
  IMAP\Connection クラスのインスタンス。

### 戻り値

現在のメールボックスにある新しいメッセージの数を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | 引数 `imap` は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な `imap` resource が期待されていました。

### 参考

- imap_num_msg() - 現在のメールボックスのメッセージ数を取得する
- imap_status() - 現在のメールボックス以外のメールボックスのステータス情報を返す

# imap_open

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_open — メールボックスへの IMAP ストリームをオープンする

### 説明

function 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 のインスタンスを返すようになりました。 これより前のバージョンでは、 resource を返していました。

### 例

例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_ping

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_ping — IMAP ストリームがアクティブかどうかを調べる

### 説明

function imap_ping(IMAP\Connection `$imap`): bool

imap_ping() はストリームに ping を行い、 まだアクティブであるかどうかを調べます。これにより新しいメールの到着を知ることもあります。 これは、定期的に「メールのチェック」を行い、サーバーとの 「接続を保持し続ける」ためのお勧めの方法です。

### パラメータ

`imap`
  IMAP\Connection クラスのインスタンス。

### 戻り値

ストリームがまだ有効であれば `true` を、そうでなければ `false` を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | 引数 `imap` は、IMAP\Connection クラスのインスタンスを期待するようになりました。 これより前のバージョンでは、有効な `imap` resource が期待されていました。

### 例

例1 imap_ping() の例

    <?php

    $imap = imap_open("{imap.example.org}", "mailadmin", "password");

    // しばらく休んだ後
    if (!imap_ping($imap)) {
        // 再接続の処理
    }

    ?>

# imap_qprint

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_qprint — quoted-printable 文字列を 8 ビット文字列に変換する

### 説明

function imap_qprint(string `$string`): string|false

（» RFC2045, section 6.7 に基づき）quoted-printable 文字列を 8 ビット文字列に変換します。

### パラメータ

`string`

  quoted-printable 文字列。

### 戻り値

8 ビット文字列を返します。 失敗した場合に `false` を返します

### 参考

- imap_8bit() - 8 ビット文字列を quoted-printable 文字列に変換する

# imap_rename

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rename — imap_renamemailbox() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 imap_renamemailbox().

# imap_renamemailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_renamemailbox — メールボックスの名前を変更する

### 説明

function 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` resource が期待されていました。

### 参考

- imap_createmailbox() - 新しいメールボックスを作る
- imap_deletemailbox() - メールボックスを削除する

# imap_reopen

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_reopen — 新規メールボックスへの IMAP ストリームを再度オープンする

### 説明

function 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` resource が期待されていました。

### 例

例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_rfc822_parse_adrlist

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rfc822_parse_adrlist — アドレス文字列を解釈します

### 説明

function 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_headers

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rfc822_parse_headers — 文字列からメールヘッダを解釈する

### 説明

function 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_write_address

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_rfc822_write_address — 指定したメールボックス、ホスト、個人情報を、 電子メールアドレスとして適当な形式にして返す

### 説明

function 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_savebody

(PHP 5 >= 5.1.3, PHP 7, PHP 8)

imap_savebody — 指定した本文部をファイルに保存する

### 説明

function 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` resource が期待されていました。

### 参考

- imap_fetchbody() - メッセージ本文中の特定のセクションを取り出す

# imap_scan

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_scan — imap_listscan() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 imap_listscan().

# imap_scanmailbox

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_scanmailbox — imap_listscan() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 imap_listscan().

# imap_search

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_search — 指定した検索条件にマッチするメッセージを配列として返す

### 説明

function 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` resource が期待されていました。

### 例

例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_set_quota

(PHP 4 >= 4.0.5, PHP 5, PHP 7, PHP 8)

imap_set_quota — 指定したメールボックスにクォータを設定する

### 説明

function 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` resource が期待されていました。

### 例

例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() - クオータレベルの設定、メールボックス毎の使用状況を取得する

# imap_setacl

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imap_setacl — 指定したメールボックスの ACL を設定する

### 説明

function 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` resource が期待されていました。

### 注意

この関数は、現在 c-client2000 以降のユーザーのみ使用可能です。

### 参考

- imap_getacl() - 与えられたメールボックスの ACL を取得する

# imap_setflag_full

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_setflag_full — メッセージにフラグをセットする

### 説明

function 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` resource が期待されていました。
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_sort

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_sort — メッセージヘッダの配列をソートする

### 説明

function 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` resource が期待されていました。
8.0.0 | `reverse` の型が、int から bool に変更されました。
8.0.0 | `search_criteria`, `charset` は、 nullable になりました。

# imap_status

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_status — 現在のメールボックス以外のメールボックスのステータス情報を返す

### 説明

function 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` resource が期待されていました。

### 例

例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_subscribe

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_subscribe — メールボックスを購読する

### 説明

function 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` resource が期待されていました。

### 参考

- imap_unsubscribe() - メールボックスの購読をやめる

# imap_thread

(PHP 4 >= 4.0.7, PHP 5, PHP 7, PHP 8)

imap_thread — スレッド化したメッセージのツリーを返す

### 説明

function 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` resource が期待されていました。

### 例

例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_timeout

(PHP 4 >= 4.3.3, PHP 5, PHP 7, PHP 8)

imap_timeout — imap タイムアウトを設定あるいは取得する

### 説明

function 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";

    ?>

# imap_uid

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_uid — 指定したメッセージシーケンス番号の UID を返す

### 説明

function 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` resource が期待されていました。

### 注意

> 注意:

> この関数は、POP3 メールボックスではサポートされません。

### 参考

- imap_msgno() - 指定した UID のメッセージ番号を返す

# imap_undelete

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_undelete — 削除マークがついているメッセージのマークをはずす

### 説明

function 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` resource が期待されていました。

### 参考

- imap_delete() - 現在のメールボックスから削除するメッセージに印を付ける
- imap_mail_move() - 指定されたメッセージをメールボックスに移動する

# imap_unsubscribe

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_unsubscribe — メールボックスの購読をやめる

### 説明

function 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` resource が期待されていました。

### 参考

- imap_subscribe() - メールボックスを購読する

# imap_utf7_decode

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_utf7_decode — 修正版 UTF-7 エンコードされた文字列をデコードする

### 説明

function 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 テキストに変換する

# imap_utf7_encode

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_utf7_encode — ISO-8859-1 文字列を修正版 UTF-7 テキストに変換する

### 説明

function 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 エンコードされた文字列をデコードする

# imap_utf8

(PHP 4, PHP 5, PHP 7, PHP 8)

imap_utf8 — MIME エンコードされたテキストを UTF-8 に変換する

### 説明

function 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 SchluÌˆter

### 参考

- imap_mime_header_decode() - MIME ヘッダ要素をデコードする

# imap_utf8_to_mutf7

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

imap_utf8_to_mutf7 — UTF-8 文字列を修正UTF-7にエンコードする

### 説明

function 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_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 クラス

(PHP 8 >= 8.1.0)

## はじめに

PHP 8.1.0 以降、`imap` リソースを置き換える、 完全不透明クラスです。

## クラス概要

final class IMAP\Connection {
}

- インストール/設定
  - 要件
  - インストール手順
  - 実行時設定
  - リソース型
- 定義済み定数
- 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 クラス

# メール

# はじめに

mail() 関数によりメールを送信できるようになります。

# インストール/設定

## 目次

- 要件
- 実行時設定

## 要件

メール関数を使用可能にするには、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.mixed_lf_and_crlf | "0" | `INI_SYSTEM`|`INI_PERDIR` | PHP 8.2.4 で追加されました。
mail.log | NULL | `INI_SYSTEM`|`INI_PERDIR` |
mail.force_extra_parameters | NULL | `INI_SYSTEM` |
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.mixed_lf_and_crlf` bool

  メールヘッダとメッセージボディの改行をLF(Line Feed) に戻せるようにします。 これは、PHP 7 の RFC に準拠しない振る舞いを真似るものです。 この設定は、メールヘッダとメッセージの改行コード CRLF(Carriage Return + Line Feed) を正しく処理できない RFC 非準拠の MTA と互換性を取るために提供されています。

`mail.force_extra_parameters` string

  指定したパラメータを、sendmail バイナリへの追加パラメータとして強制的に渡します。 これらのパラメータは、常に mail() の第 5 パラメータの値を上書きします。

  `INI_SYSTEM` のデフォルトの振る舞いに加えて、 この値は httpd.conf の `php_value` を使って設定することもできます(が、お勧めはしません)。
`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

(PHP 4 >= 4.0.2, PHP 5, PHP 7)

ezmlm_hash — EZMLM で必要なハッシュ値を計算する

警告

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

### 説明

function ezmlm_hash(string `$addr`): int

ezmlm_hash() は、EZMLM メイリングリストを MySQL データベースで管理する際に必要なハッシュ値を計算します。

### パラメータ

`addr`

  ハッシュ値を計算する email アドレス。

### 戻り値

`addr` のハッシュ値を返します。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | この関数は削除されました。
7.2.0 | この関数は推奨されなくなりました。

### 例

例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インターフェイスを使用します

    ?>

# mail

(PHP 4, PHP 5, PHP 7, PHP 8)

mail — メールを送信する

### 説明

function 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

## 目次

- ezmlm_hash — EZMLM で必要なハッシュ値を計算する
- mail — メールを送信する

- インストール/設定
  - 要件
  - 実行時設定
- メール 関数
  - ezmlm_hash — EZMLM で必要なハッシュ値を計算する
  - mail — メールを送信する

# Mailparse

# はじめに

Mailparse は、電子メールのメッセージをパースして処理するための拡張モジュールです。 » RFC 822 および » RFC 2045 (`MIME`) に準拠したメッセージを扱うことができます。

Mailparse はストリームベースで動作します。つまり、 処理する際にファイルの内容をメモリにコピーする必要がないということです。 これにより、大きなメッセージを扱う際にリソースを効率的に使用することができます。

> 注意: Mailparse には、mbstring 拡張モジュールが必要です。 また、mbstring は 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_EXTRACT_OUTPUT` (int)
`MAILPARSE_EXTRACT_STREAM` (int)
`MAILPARSE_EXTRACT_RETURN` (int)

# Mailparse 関数

# mailparse_determine_best_xfer_encoding

(PECL mailparse >= 0.9.0)

mailparse_determine_best_xfer_encoding — 最も適したエンコーディングを取得する

### 説明

function 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

# mailparse_msg_create

(PECL mailparse >= 0.9.0)

mailparse_msg_create — mime メールリソースを作成する

### 説明

function mailparse_msg_create(): resource

`MIME` メールリソースを作成します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

メッセージのパースに使用するハンドルを返します。

### 注意

> 注意: この関数が作成したリソースが必要なくなった際は、 メモリリークを避けるため mailparse_msg_free() をコールすることを推奨します。

### 参考

- mailparse_msg_free() - MIME リソースを解放する
- mailparse_msg_parse_file() - ファイルをパースする

# mailparse_msg_extract_part

(PECL mailparse >= 0.9.0)

mailparse_msg_extract_part — メッセージセクションを展開/デコードする

### 説明

function 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_file

(PECL mailparse >= 0.9.0)

mailparse_msg_extract_part_file — メッセージセクションを展開/デコードする

### 説明

function 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 をデコードせずに展開する

# mailparse_msg_extract_whole_part_file

(PECL mailparse >= 0.9.0)

mailparse_msg_extract_whole_part_file — ヘッダを含むメッセージセクションを、transfer encoding をデコードせずに展開する

### 説明

function 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() - メッセージセクションを展開/デコードする

# mailparse_msg_free

(PECL mailparse >= 0.9.0)

mailparse_msg_free — MIME リソースを解放する

### 説明

function 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() - ファイルをパースする

# mailparse_msg_get_part

(PECL mailparse >= 0.9.0)

mailparse_msg_get_part — MIME メッセージの指定したセクションに関するハンドルを返す

### 説明

function mailparse_msg_get_part(resource `$mimemail`, string `$mimesection`): resource
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`mimemail`
  有効な `MIME` リソース。
`mimesection`

# mailparse_msg_get_part_data

(PECL mailparse >= 0.9.0)

mailparse_msg_get_part_data — メッセージに関する情報の連想配列を返す

### 説明

function mailparse_msg_get_part_data(resource `$mimemail`): array
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`mimemail`
  有効な `MIME` リソース。

# mailparse_msg_get_structure

(PECL mailparse >= 0.9.0)

mailparse_msg_get_structure — 指定したメッセージ内の MIME セクション名の配列を返す

### 説明

function mailparse_msg_get_structure(resource `$mimemail`): array
警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`mimemail`
  有効な `MIME` リソース。

# mailparse_msg_parse

(PECL mailparse >= 0.9.0)

mailparse_msg_parse — データをパースし、バッファに追加する

### 説明

function mailparse_msg_parse(resource `$mimemail`, string `$data`): bool

データを順にパースし、指定した mime メールリソースに格納します。

この関数により、ファイル全体を読み込んでからパースするのではなく 読み込んだ部分から順に処理していくことができます。

### パラメータ

`mimemail`
  有効な `MIME` リソース。
`data`

  > 注意: `data` の最後のチャンクは、 改行コード(`CRLF`) で終わることが想定されています。 そうでない場合、最後の行がパースされません。

### 戻り値

成功した場合に `true` を、失敗した場合に `false` を返します。

# mailparse_msg_parse_file

(PECL mailparse >= 0.9.0)

mailparse_msg_parse_file — ファイルをパースする

### 説明

function mailparse_msg_parse_file(string `$filename`): resource

ファイルをパースします。 ディスク上にあるメールファイルをパースするための最良の方法です。

### パラメータ

`filename`
  メッセージを保持するファイルへのパス。 このファイルがオープンされ、ストリームとしてパーサーに流し込まれます。

  > 注意: `filename` が保持するメッセージは、 改行コード(`CRLF`) で終わることが想定されています。 そうでない場合、最後の行がパースされません。

### 戻り値

構造を表す `MIME` リソース、あるいはエラー時に `false` を返します。

### 注意

> 注意: この関数が作成したリソースが必要なくなった際は、 メモリリークを避けるため mailparse_msg_free() をコールすることを推奨します。

### 参考

- mailparse_msg_free() - MIME リソースを解放する
- mailparse_msg_create() - mime メールリソースを作成する

# mailparse_rfc822_parse_addresses

(PECL mailparse >= 0.9.0)

mailparse_rfc822_parse_addresses — RFC 822 準拠のアドレスをパースする

### 説明

function 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_stream_encode

(PECL mailparse >= 0.9.0)

mailparse_stream_encode — ソースファイルポインタからストリームデータを取得し、 エンコーディングを適用し、出力ファイルポインタに書き込む

### 説明

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

# mailparse_uudecode_all

(PECL mailparse >= 0.9.0)

mailparse_uudecode_all — ファイルポインタからデータをスキャンし、uuencode されたファイルを展開する

### 説明

function 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

## 目次

- 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_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 されたファイルを展開する

- IMAP — IMAP、POP3 および NNTP
  - インストール/設定
  - 定義済み定数
  - IMAP 関数
  - IMAP\Connection — IMAP\Connection クラス
- メール
  - インストール/設定
  - メール 関数
- Mailparse
  - インストール/設定
  - 定義済み定数
  - Mailparse 関数

# 数学

# BCMath 任意精度数学関数

# はじめに

任意の精度の演算をサポートするために、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が構築オプション --enable-bcmath を付けてコンパイルされている場合にのみ使用できます。

Windows 版の `PHP` には この拡張モジュールのサポートが組み込まれています。これらの関数を使用 するために拡張モジュールを追加でロードする必要はありません。

## 実行時設定

php.ini の設定により動作が変化します。

BC 数学関数設定オプション
名前 | デフォルト | 変更可能 | 変更履歴
--- | --- | --- | ---
bcmath.scale | "0" | `INI_ALL` |

INI_* モードの詳細および定義については どこで設定を行うのか を参照してください。

以下に設定ディレクティブに関する 簡単な説明を示します。

`bcmath.scale` int

  全ての bcmath 関数に関する 10 進桁数。 bcscale() も参照ください。

  > 注意: BcMath\Number クラスは、この設定の影響を受けません。

# BC Math 関数

# bcadd

(PHP 4, PHP 5, PHP 7, PHP 8)

bcadd — 2つの任意精度の数値を加算する

### 説明

function bcadd(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

`num1` を `num2` に加算します。

### パラメータ

`num1`

  左オペランドを表す文字列。

`num2`

  右オペランドを表す文字列。

`scale`
  結果の小数点以下の桁数を指定します。`null` の場合は、 bcscale() 関数でグローバルに 設定した桁数をデフォルトとして使用します。 それも設定されていない場合は `bcmath.scale` INI ディレクティブの値を使用します。

### 戻り値

二つの数の和を文字列で返します。

### エラー / 例外

この関数は、以下の場合に ValueError をスローします:

- `num1` もしくは `num1` が、BCMath で有効でない数値形式の文字列である場合
- `scale` が範囲外の値である場合

### 変更履歴

バージョン | 説明
--- | ---
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() - 任意精度数値の減算を行う
- BcMath\Number::add() - 任意精度の数値を加算する

# bcceil

(PHP 8 >= 8.4.0)

bcceil — 任意精度数値を切り上げる

### 説明

function bcceil(string `$num`): string

必要に応じて `num` を切り上げ、 `num` の次に大きい整数値を返します。

### パラメータ

`num`
  切り上げる値を表す文字列。

### 戻り値

`num` に最も近い整数に切り上げられた数値を表す数値形式の文字列を返します。

### エラー / 例外

この関数は、`num` が BCMath で有効でない数値形式の文字列である場合、ValueError をスローします。

### 例

例1 bcceil() の例

    <?php
    var_dump(bcceil('4.3'));
    var_dump(bcceil('9.999'));
    var_dump(bcceil('-3.14'));
    ?>

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

    string(1) "5"
    string(2) "10"
    string(2) "-3"

### 参考

- bcfloor() - 任意精度数値を切り下げる
- bcround() - 任意精度数値を丸める
- BcMath\Number::ceil() - 任意精度数値を切り上げる

# bccomp

(PHP 4, PHP 5, PHP 7, PHP 8)

bccomp — 2 つの任意精度数値を比較する

### 説明

function bccomp(string `$num1`, string `$num2`, ?int `$scale` = `null`): int

`num1` と `num2` を比較し、 比較結果を整数値で返します。

### パラメータ

`num1`

  左オペランドを表す文字列。

`num2`

  右オペランドを表す文字列。

`scale`
  結果の小数点以下の桁数を指定します。`null` の場合は、 bcscale() 関数でグローバルに 設定した桁数をデフォルトとして使用します。 それも設定されていない場合は `bcmath.scale` INI ディレクティブの値を使用します。

### 戻り値

ふたつのオペランドが等しければ `0`、 `num1` が `num2` より大きければ戻り値は `1`、小さければ `-1` を返します。

### エラー / 例外

この関数は、以下の場合に ValueError をスローします:

- `num1` もしくは `num1` が、BCMath で有効でない数値形式の文字列である場合
- `scale` が範囲外の値である場合

### 変更履歴

バージョン | 説明
--- | ---
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

    ?>

### 参考

- BcMath\Number::compare() - 任意精度数値を比較する

# bcdiv

(PHP 4, PHP 5, PHP 7, PHP 8)

bcdiv — 2つの任意精度数値で除算を行う

### 説明

function bcdiv(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

`num1` を `num2` で除算します。

### パラメータ

`num1`

  被除数を表す文字列。

`num2`

  割る数を表す文字列。

`scale`
  結果の小数点以下の桁数を指定します。`null` の場合は、 bcscale() 関数でグローバルに 設定した桁数をデフォルトとして使用します。 それも設定されていない場合は `bcmath.scale` INI ディレクティブの値を使用します。

### 戻り値

除算結果を文字列で返します。 `num2` が `0` の場合は `null` を返します。

### エラー / 例外

この関数は、以下の場合に ValueError をスローします:

- `num1` もしくは `num1` が、BCMath で有効でない数値形式の文字列である場合
- `scale` が範囲外の値である場合

この関数は、 `num2` が `0` である場合、 DivisionByZeroError 例外をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `scale` は、nullable になりました。

### 例

例1 bcdiv() の例

    <?php

    echo bcdiv('105', '6.55957', 3);  // 16.007

    ?>

### 参考

- bcmul() - 2つの任意精度数値の乗算を行う
- BcMath\Number::div() - 任意精度数値の除算を行う

# bcdivmod

(PHP 8 >= 8.4.0)

bcdivmod — 任意精度数値の商と剰余を取得する

### 説明

function bcdivmod(string `$num1`, string `$num2`, ?int `$scale` = `null`): array

`num1` を `num2` で割った商と剰余を取得します。

### パラメータ

`num1`

  被除数を表す文字列。

`num2`

  割る数を表す文字列。

`scale`
  結果の小数点以下の桁数を指定します。`null` の場合は、 bcscale() 関数でグローバルに 設定した桁数をデフォルトとして使用します。 それも設定されていない場合は `bcmath.scale` INI ディレクティブの値を使用します。

### 戻り値

1つ目の要素に商の値を表す string が、2つ目の要素に剰余の値を表す string が格納された配列を返します。

### エラー / 例外

この関数は、以下の場合に ValueError をスローします:

- `num1` もしくは `num1` が、BCMath で有効でない数値形式の文字列である場合
- `scale` が範囲外の値である場合

この関数は、 `num2` が `0` である場合、 DivisionByZeroError 例外をスローします。

### 例

例1 bcdivmod() の例

    <?php
    bcscale(0);

    [$quot, $rem] = bcdivmod('5',  '3');
    echo $quot; // 1
    echo $rem;  // 2

    [$quot, $rem] = bcdivmod('5',  '-3');
    echo $quot; // -1
    echo $rem;  // 2

    [$quot, $rem] = bcdivmod('-5',  '3');
    echo $quot; // -1
    echo $rem;  // -2

    [$quot, $rem] = bcdivmod('-5',  '-3');
    echo $quot; // 1
    echo $rem;  // -2
    ?>

例2 bcdivmod() に小数の値を指定する

    <?php
    [$quot, $rem] = bcdivmod('5.7', '1.3', 1);
    echo $quot; // 4
    echo $rem;  // 0.5
    ?>

### 参考

- bcdiv() - 2つの任意精度数値で除算を行う
- bcmod() - 2 つの任意精度数値の剰余を取得する
- BcMath\Number::divmod() - 任意精度数値の商と剰余を取得する

# bcfloor

(PHP 8 >= 8.4.0)

bcfloor — 任意精度数値を切り下げる

### 説明

function bcfloor(string `$num`): string

必要に応じて `num` を切り下げ、 `num` の次に小さい整数値を返します。

### パラメータ

`num`
  切り上げる値を表す文字列。

### 戻り値

`num` に最も近い整数に切り下げられた数値を表す数値形式の文字列を返します。

### エラー / 例外

この関数は、`num` が BCMath で有効でない数値形式の文字列である場合、ValueError をスローします。

### 例

例1 bcfloor() の例

    <?php
    var_dump(bcfloor('4.3'));
    var_dump(bcfloor('9.999'));
    var_dump(bcfloor('-3.14'));
    ?>

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

    string(1) "4"
    string(1) "9"
    string(2) "-4"

### 参考

- bcceil() - 任意精度数値を切り上げる
- bcround() - 任意精度数値を丸める
- BcMath\Number::floor() - 任意精度数値を切り下げる

# bcmod

(PHP 4, PHP 5, PHP 7, PHP 8)

bcmod — 2 つの任意精度数値の剰余を取得する

### 説明

function bcmod(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

`num1` の、 `num2` を法とする剰余を取得します。 結果は `num1` と同じ符号を持ちます。

### パラメータ

`num1`

  左オペランドを表す文字列。

`num2`

  右オペランドを表す文字列。

`scale`
  結果の小数点以下の桁数を指定します。`null` の場合は、 bcscale() 関数でグローバルに 設定した桁数をデフォルトとして使用します。 それも設定されていない場合は `bcmath.scale` INI ディレクティブの値を使用します。

### 戻り値

剰余を文字列で返します。 `num2` が 0 の場合は `null` を返します。

### エラー / 例外

この関数は、以下の場合に ValueError をスローします:

- `num1` もしくは `num1` が、BCMath で有効でない数値形式の文字列である場合
- `scale` が範囲外の値である場合

この関数は、 `num2` が `0` である場合、 DivisionByZeroError 例外をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `scale` は nullable になりました。
8.0.0 | `0` 除算を行うと、DivisionByZeroError 例外がスローされるようになりました。以前は `null` が返されていました。
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つの任意精度数値で除算を行う
- BcMath\Number::mod() - 任意精度数値の剰余を取得する

# bcmul

(PHP 4, PHP 5, PHP 7, PHP 8)

bcmul — 2つの任意精度数値の乗算を行う

### 説明

function bcmul(string `$num1`, string `$num2`, ?int `$scale` = `null`): string

`num1` に `num2` を掛けます。

### パラメータ

`num1`

  左オペランドを表す文字列。

`num2`

  右オペランドを表す文字列。

`scale`
  結果の小数点以下の桁数を指定します。`null` の場合は、 bcscale() 関数でグローバルに 設定した桁数をデフォルトとして使用します。 それも設定されていない場合は `bcmath.scale` INI ディレクティブの値を使用します。

### 戻り値

結果を文字列で返します。

### エラー / 例外

この関数は、以下の場合に ValueError をスローします:

- `num1` もしくは `num1` が、BCMath で有効でない数値形式の文字列である場合
- `scale` が範囲外の値である場合

### 変更履歴

バージョン | 説明
--- | ---
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つの任意精度数値で除算を行う
- BcMath\Number::mul() - 任意精度数値の乗算を行う

# bcpow

(PHP 4, PHP 5, PHP 7, PHP 8)

bcpow — 任意精度数値をべき乗する

### 説明

function bcpow(string `$num`, string `$exponent`, ?int `$scale` = `null`): string

`num` の `exponent` 乗を求めます。

### パラメータ

`num`

  基数を表す文字列。

`exponent`

  指数を表す文字列。 指数が整数でない場合、値は切り捨てられます。 正しい指数の範囲はプラットフォーム依存ですが、 少なくとも `-2147483648` から `2147483647` までの範囲を持ちます。

`scale`
  結果の小数点以下の桁数を指定します。`null` の場合は、 bcscale() 関数でグローバルに 設定した桁数をデフォルトとして使用します。 それも設定されていない場合は `bcmath.scale` INI ディレクティブの値を使用します。

### 戻り値

結果を文字列で返します。

### エラー / 例外

この関数は、以下の場合に ValueError をスローします:

- `num` もしくは `exponent` が、BCMath で有効でない数値形式の文字列である場合
- `exponent` が整数値でない場合
- `exponent` もしくは `scale` が範囲外の値である場合

この関数は、`num` の値が `0` かつ `exponent` が負の値である場合、 DivisionByZeroError 例外をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | `0` の負のべき乗を行った場合、`0` を返す代わりに DivisionByZeroError がスローされるようになりました。
8.0.0 | `exponent` が小数部を持つ場合、ValueError がスローされるようになりました。 以前は、小数部を切り捨てて整数として計算を行っていました。
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() - 任意精度数値の平方根を取得する
- BcMath\Number::pow() - 任意精度数値をべき乗する

# bcpowmod

(PHP 5, PHP 7, PHP 8)

bcpowmod — 任意精度数値のべき乗の、指定した数値による剰余

### 説明

function bcpowmod(
string `$num`,
string `$exponent`,
string `$modulus`,
?int `$scale` = `null`
): string

`modulus` で割った余りを求めることを考慮して、 `num` の `exponent` 乗を高速に計算します。

### パラメータ

`num`

  基数を表す整数の文字列。 (つまり、scale は 0 でなければいけません)

`exponent`

  指数を表す、負でない、整数の文字列。 (つまり、scale は 0 でなければいけません)

`modulus`

  法を表す、整数の文字列。 (つまり、scale は 0 でなければいけません)

`scale`
  結果の小数点以下の桁数を指定します。`null` の場合は、 bcscale() 関数でグローバルに 設定した桁数をデフォルトとして使用します。 それも設定されていない場合は `bcmath.scale` INI ディレクティブの値を使用します。

### 戻り値

結果を文字列で返します。

### エラー / 例外

この関数は、以下の場合に ValueError をスローします:

- `num` か `exponent` か `modulus` のいずれかが、BCMath で有効でない数値形式の文字列である場合
- `num` か `exponent` か `modulus` のいずれかが整数値でない場合
- `exponent` が負の値である場合
- `scale` が範囲外の値である場合

この関数は、`modulus` の値が `0` である場合、 DivisionByZeroError 例外をスローします。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `scale` は、nullable になりました。
8.0.0 | `exponent` が負の値の場合、`false` を返す代わりに ValueError をスローするようになりました。
8.0.0 | `0` 除算を行うと、DivisionByZeroError 例外がスローされるようになりました。以前は `false` が返されていました。

### 例

以下の 2 つの文は機能的に同じです。しかし bcpowmod() バージョンのほうが実行時間が早いうえ、 より大きな値の計算が可能です。

    <?php
    $a = bcpowmod($x, $y, $mod);

    $b = bcmod(bcpow($x, $y), $mod);

    // $a と $b は同じ値になります

    ?>

### 注意

> 注意:

> このメソッドでは剰余計算を行っているので、 正の整数以外を指定すると予期せぬ結果となります。

### 参考

- bcpow() - 任意精度数値をべき乗する
- bcmod() - 2 つの任意精度数値の剰余を取得する
- BcMath\Number::powmod() - 任意精度数値のべき乗の、指定した数値による剰余

# bcround

(PHP 8 >= 8.4.0)

bcround — 任意精度数値を丸める

### 説明

function bcround(string `$num`, int `$precision` = 0, RoundingMode `$mode` = `RoundingMode::HalfAwayFromZero`): string

`num` を、指定した `precision`(小数点以下の桁数)に丸めた値を返します。 `precision` を負またはゼロ(デフォルト) とすることも可能です。

### パラメータ

`num`

  丸める値。

`precision`

  オプションで指定する、丸める桁数。

  `precision` が正の値の場合、 `num` は 小数点以下、有効桁数 `precision` 桁に丸められます。

  `precision` が負の場合、 `num` の 丸め処理は小数点より前の `precision` 桁に対して行われます。 つまり、一番近い `pow(10, -$precision)` の倍数に丸められます。 たとえば、`precision` が -1 の場合、 `num` は 一番近い10の倍数に、 `precision` が -2 の場合は 一番近い100の倍数に丸められる、という具合です。

`mode`
  指定する丸めモード。詳しくは RoundingMode を参照してください。

### 戻り値

`num` を指定された精度へ丸めた数値を表す文字列を返します。

### エラー / 例外

この関数は、以下の場合に ValueError をスローします:

- `num` が、BCMath で有効でない数値形式の文字列である場合
- 無効な `mode` を指定した場合

### 例

例1 bcround() の例

    <?php
    var_dump(bcround('3.4'));
    var_dump(bcround('3.5'));
    var_dump(bcround('3.6'));
    var_dump(bcround('3.6', 0));
    var_dump(bcround('5.045', 2));
    var_dump(bcround('5.055', 2));
    var_dump(bcround('345', -2));
    var_dump(bcround('345', -3));
    var_dump(bcround('678', -2));
    var_dump(bcround('678', -3));
    ?>

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

    string(1) "3"
    string(1) "4"
    string(1) "4"
    string(1) "4"
    string(4) "5.05"
    string(4) "5.06"
    string(3) "300"
    string(1) "0"
    string(3) "700"
    string(4) "1000"

例2 bcround() で異なる `precision` を指定した例

    <?php
    $number = '123.45';

    var_dump(bcround($number, 3));
    var_dump(bcround($number, 2));
    var_dump(bcround($number, 1));
    var_dump(bcround($number, 0));
    var_dump(bcround($number, -1));
    var_dump(bcround($number, -2));
    var_dump(bcround($number, -3));
    ?>

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

    string(7) "123.450"
    string(6) "123.45"
    string(5) "123.5"
    string(3) "123"
    string(3) "120"
    string(3) "100"
    string(1) "0"

例3 bcround() で異なる `mode` を指定した例

    <?php
    echo 'Rounding modes with 9.5' . PHP_EOL;
    var_dump(bcround('9.5', 0, RoundingMode::HalfAwayFromZero));
    var_dump(bcround('9.5', 0, RoundingMode::HalfTowardsZero));
    var_dump(bcround('9.5', 0, RoundingMode::HalfEven));
    var_dump(bcround('9.5', 0, RoundingMode::HalfOdd));
    var_dump(bcround('9.5', 0, RoundingMode::TowardsZero));
    var_dump(bcround('9.5', 0, RoundingMode::AwayFromZero));
    var_dump(bcround('9.5', 0, RoundingMode::NegativeInfinity));
    var_dump(bcround('9.5', 0, RoundingMode::PositiveInfinity));

    echo PHP_EOL;
    echo 'Rounding modes with 8.5' . PHP_EOL;
    var_dump(bcround('8.5', 0, RoundingMode::HalfAwayFromZero));
    var_dump(bcround('8.5', 0, RoundingMode::HalfTowardsZero));
    var_dump(bcround('8.5', 0, RoundingMode::HalfEven));
    var_dump(bcround('8.5', 0, RoundingMode::HalfOdd));
    var_dump(bcround('8.5', 0, RoundingMode::TowardsZero));
    var_dump(bcround('8.5', 0, RoundingMode::AwayFromZero));
    var_dump(bcround('8.5', 0, RoundingMode::NegativeInfinity));
    var_dump(bcround('8.5', 0, RoundingMode::PositiveInfinity));
    ?>

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

    Rounding modes with 9.5
    string(2) "10"
    string(1) "9"
    string(2) "10"
    string(1) "9"
    string(1) "9"
    string(2) "10"
    string(1) "9"
    string(2) "10"

    Rounding modes with 8.5
    string(1) "9"
    string(1) "8"
    string(1) "8"
    string(1) "9"
    string(1) "8"
    string(1) "9"
    string(1) "8"
    string(1) "9"

例4 bcround() で `precision` を指定し、 異なる `mode` を指定した例

    <?php
    echo 'Using RoundingMode::HalfAwayFromZero with 1 decimal digit precision' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::HalfAwayFromZero));
    var_dump(bcround(-1.55, 1, RoundingMode::HalfAwayFromZero));

    echo PHP_EOL;
    echo 'Using RoundingMode::HalfTowardsZero with 1 decimal digit precision' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::HalfTowardsZero));
    var_dump(bcround(-1.55, 1, RoundingMode::HalfTowardsZero));

    echo PHP_EOL;
    echo 'Using RoundingMode::HalfEven with 1 decimal digit precision' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::HalfEven));
    var_dump(bcround(-1.55, 1, RoundingMode::HalfEven));

    echo PHP_EOL;
    echo 'Using RoundingMode::HalfOdd with 1 decimal digit precision' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::HalfOdd));
    var_dump(bcround(-1.55, 1, RoundingMode::HalfOdd));

    echo PHP_EOL;
    echo 'Using RoundingMode::TowardsZero with 1 decimal digit precision' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::TowardsZero));
    var_dump(bcround(-1.55, 1, RoundingMode::TowardsZero));

    echo PHP_EOL;
    echo 'Using RoundingMode::AwayFromZero with 1 decimal digit precision' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::AwayFromZero));
    var_dump(bcround(-1.55, 1, RoundingMode::AwayFromZero));

    echo PHP_EOL;
    echo 'Using RoundingMode::NegativeInfinity with 1 decimal digit precision' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::NegativeInfinity));
    var_dump(bcround(-1.55, 1, RoundingMode::NegativeInfinity));

    echo PHP_EOL;
    echo 'Using RoundingMode::PositiveInfinity with 1 decimal digit precision' . PHP_EOL;
    var_dump(bcround( 1.55, 1, RoundingMode::PositiveInfinity));
    var_dump(bcround(-1.55, 1, RoundingMode::PositiveInfinity));
    ?>

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

    Using RoundingMode::HalfAwayFromZero with 1 decimal digit precision
    string(3) "1.6"
    string(4) "-1.6"

    Using RoundingMode::HalfTowardsZero with 1 decimal digit precision
    string(3) "1.5"
    string(4) "-1.5"

    Using RoundingMode::HalfEven with 1 decimal digit precision
    string(3) "1.6"
    string(4) "-1.6"

    Using RoundingMode::HalfOdd with 1 decimal digit precision
    string(3) "1.5"
    string(4) "-1.5"

    Using RoundingMode::TowardsZero with 1 decimal digit precision
    string(3) "1.5"
    string(4) "-1.5"

    Using RoundingMode::AwayFromZero with 1 decimal digit precision
    string(3) "1.6"
    string(4) "-1.6"

    Using RoundingMode::NegativeInfinity with 1 decimal digit precision
    string(3) "1.5"
    string(4) "-1.6"

    Using RoundingMode::PositiveInfinity with 1 decimal digit precision
    string(3) "1.6"
    string(4) "-1.5"

### 参考

- bcceil() - 任意精度数値を切り上げる
- bcfloor() - 任意精度数値を切り下げる
- BcMath\Number::round() - 任意精度数値を丸める

# bcscale

(PHP 4, PHP 5, PHP 7, PHP 8)

bcscale — すべての BC 演算関数におけるデフォルトのスケールを設定/取得する

### 説明

function bcscale(int `$scale`): int

デフォルトのスケールを設定します。これ以降、 BC 演算関数で明示的にスケールを指定しなかった場合にこの値を使用します。

function bcscale(null `$scale` = `null`): int

現在のスケールを取得します。

### パラメータ

`scale`

  スケール。

### 戻り値

スケールを設定する場合は、古いスケールを返します。 そうでない場合、現在のスケールを返します。

### エラー / 例外

This function throws a ValueError if `scale` is outside the valid range.

### 変更履歴

バージョン | 説明
--- | ---
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

    ?>

# bcsqrt

(PHP 4, PHP 5, PHP 7, PHP 8)

bcsqrt — 任意精度数値の平方根を取得する

### 説明

function bcsqrt(string `$num`, ?int `$scale` = `null`): string

`num` の平方根を返します。

### パラメータ

`num`

  オペランドを表す、BCMath で有効な数値形式の文字列。

`scale`
  結果の小数点以下の桁数を指定します。`null` の場合は、 bcscale() 関数でグローバルに 設定した桁数をデフォルトとして使用します。 それも設定されていない場合は `bcmath.scale` INI ディレクティブの値を使用します。

### 戻り値

平方根を、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() - 任意精度数値をべき乗する
- BcMath\Number::sqrt() - 任意精度数値の平方根を取得する

# bcsub

(PHP 4, PHP 5, PHP 7, PHP 8)

bcsub — 任意精度数値の減算を行う

### 説明

function bcsub(string `$left_operand`, string `$right_operand`, int `$scale` = 0): string

`left_operand` から `right_operand` を引きます。

### パラメータ

`num1`

  左オペランドを表す文字列。

`num2`

  右オペランドを表す文字列。

`scale`
  結果の小数点以下の桁数を指定します。`null` の場合は、 bcscale() 関数でグローバルに 設定した桁数をデフォルトとして使用します。 それも設定されていない場合は `bcmath.scale` INI ディレクティブの値を使用します。

### 戻り値

減算の結果を文字列で返します。

### エラー / 例外

この関数は、以下の場合に ValueError をスローします:

- `num1` もしくは `num1` が、BCMath で有効でない数値形式の文字列である場合
- `scale` が範囲外の値である場合

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `scale` は nullable になりました。

### 例

例1 bcsub() の例

    <?php

    $a = '1.234';
    $b = '5';

    echo bcsub($a, $b);     // -3
    echo bcsub($a, $b, 4);  // -3.7660

    ?>

### 参考

- bcadd() - 2つの任意精度の数値を加算する
- BcMath\Number::sub() - 任意精度数値の減算を行う

## 目次

- bcadd — 2つの任意精度の数値を加算する
- bcceil — 任意精度数値を切り上げる
- bccomp — 2 つの任意精度数値を比較する
- bcdiv — 2つの任意精度数値で除算を行う
- bcdivmod — 任意精度数値の商と剰余を取得する
- bcfloor — 任意精度数値を切り下げる
- bcmod — 2 つの任意精度数値の剰余を取得する
- bcmul — 2つの任意精度数値の乗算を行う
- bcpow — 任意精度数値をべき乗する
- bcpowmod — 任意精度数値のべき乗の、指定した数値による剰余
- bcround — 任意精度数値を丸める
- bcscale — すべての BC 演算関数におけるデフォルトのスケールを設定/取得する
- bcsqrt — 任意精度数値の平方根を取得する
- bcsub — 任意精度数値の減算を行う

# BcMath\Number クラス

(PHP 8 >= 8.4.0)

## はじめに

任意精度数値のクラスです。 このオブジェクトは、オーバーロードされた 算術演算子, 比較演算子 をサポートしています。

> 注意: このクラスは、php.iniで設定された bcmath.scale INI ディレクティブの影響を受けません。

> 注意: オーバーロードされた演算子の動作は、対応するメソッドで `scale` パラメータに `null` を指定した場合と同じです。

## クラス概要

namespace BcMath;
final readonly class Number implements Stringable {
/* プロパティ */
public string $value;
public int $scale;
/* メソッド */
public function __construct(string|int `$num`)
public function add(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function ceil(): BcMath\Number
public function compare(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): int
public function div(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function divmod(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): array
public function floor(): BcMath\Number
public function mod(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function mul(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function pow(BcMath\Number|string|int `$exponent`, ?int `$scale` = `null`): BcMath\Number
public function powmod(BcMath\Number|string|int `$exponent`, BcMath\Number|string|int `$modulus`, ?int `$scale` = `null`): BcMath\Number
public function round(int `$precision` = 0, RoundingMode `$mode` = `RoundingMode::HalfAwayFromZero`): BcMath\Number
public function __serialize(): array
public function sqrt(?int `$scale` = `null`): BcMath\Number
public function sub(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number
public function __toString(): string
public function __unserialize(array `$data`): void
}

## プロパティ

value
  任意精度数値の文字表現。
scale
  オブジェクトに設定されているスケールの値。 計算メソッドで明示的に `scale` パラメータが設定されていない場合、 この値は自動的に計算されて設定されます。

# BcMath\Number::add

(PHP 8 >= 8.4.0)

BcMath\Number::add — 任意精度の数値を加算する

### 説明

public function BcMath\Number::add(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

$this と `num` を加算します。

### パラメータ

`num`
  加数を表す値。
`scale`
  計算結果オブジェクトの BcMath\Number::scale を明示的に指定します。 `null` の場合、計算結果の BcMath\Number::scale は自動的に設定されます。

### 戻り値

加算結果を新しい BcMath\Number オブジェクトとして返します。

加算結果オブジェクトの BcMath\Number::scale が自動的に設定される場合、加算に使用する2つの数値のうち、 大きい方の BcMath\Number::scale が使用されます。

つまり、2つの値の BcMath\Number::scale がそれぞれ `2` と `5` の場合、 加算結果オブジェクトの BcMath\Number::scale は `5` になります。

### エラー / 例外

このメソッドは、以下の場合に ValueError をスローします:

- `num` が、BCMath で有効でない数値形式の文字列である場合
- `scale` が範囲外の値である場合

### 例

例1 BcMath\Number::add() で `scale` を指定しない例

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->add(new BcMath\Number('2.34567'));
    $ret2 = $number->add('-3.456');
    $ret3 = $number->add(7);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

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

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(7) "3.57967"
      ["scale"]=>
      int(5)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(6) "-2.222"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "8.234"
      ["scale"]=>
      int(3)
    }

例2 BcMath\Number::add() で `scale` を指定する例

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->add(new BcMath\Number('2.34567'), 1);
    $ret2 = $number->add('-3.456', 10);
    $ret3 = $number->add(7, 0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

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

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "3.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(13) "-2.2220000000"
      ["scale"]=>
      int(10)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }

### 参考

- bcadd() - 2つの任意精度の数値を加算する
- BcMath\Number::sub() - 任意精度数値の減算を行う

# BcMath\Number::ceil

(PHP 8 >= 8.4.0)

BcMath\Number::ceil — 任意精度数値を切り上げる

### 説明

public function BcMath\Number::ceil(): BcMath\Number

必要に応じて $this を切り上げ、 $this の次に大きい整数値を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

結果を新しい BcMath\Number オブジェクトとして返します。 結果の BcMath\Number::scale は常に `0` になります。

### 例

例1 BcMath\Number::ceil() の例

    <?php
    $num1 = new BcMath\Number('4.3')->ceil();
    $num2 = new BcMath\Number('9.999')->ceil();
    $num3 = new BcMath\Number('-3.14')->ceil();

    var_dump($num1, $num2, $num3);
    ?>

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

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "5"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(2) "-3"
      ["scale"]=>
      int(0)
    }

### 参考

- bcceil() - 任意精度数値を切り上げる
- BcMath\Number::floor() - 任意精度数値を切り下げる
- BcMath\Number::round() - 任意精度数値を丸める

# BcMath\Number::compare

(PHP 8 >= 8.4.0)

BcMath\Number::compare — 任意精度数値を比較する

### 説明

public function BcMath\Number::compare(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): int

任意精度数値を比較します。 このメソッドは、 宇宙船演算子 と同じように動作します。

### パラメータ

`num`
  比較する値。
`scale`
  比較に使用する `scale` を指定します。 `null` の場合、比較にはすべての桁が使用されます。

### 戻り値

2つの値が等しい場合は `0`、$this が `num` より大きい場合は `1`、小さければ `-1` を返します。

### エラー / 例外

このメソッドは、以下の場合に ValueError をスローします:

- `num` が、BCMath で有効でない数値形式の文字列である場合
- `scale` が範囲外の値である場合

### 例

例1 BcMath\Number::compare() で `scale` を指定しない例

    <?php
    $number = new BcMath\Number('1.234');

    var_dump(
        $number->compare(new BcMath\Number('1.234')),
        $number->compare('1.23400'),
        $number->compare('1.23401'),
        $number->compare(1),
    );
    ?>

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

    int(0)
    int(0)
    int(-1)
    int(1)

例2 BcMath\Number::compare() で `scale` を指定する例

    <?php
    $number = new BcMath\Number('1.234');

    var_dump(
        $number->compare(new BcMath\Number('1.299'), 1),
        $number->compare('1.24', 2),
        $number->compare('1.22', 2),
        $number->compare(1, 0),
    );
    ?>

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

    int(0)
    int(-1)
    int(1)
    int(0)

### 参考

- bccomp() - 2 つの任意精度数値を比較する

# BcMath\Number::__construct

(PHP 8 >= 8.4.0)

BcMath\Number::__construct — BcMath\Number オブジェクトを作成する

### 説明

public function BcMath\Number::__construct(string|int `$num`)

int もしくは string の値から BcMath\Number オブジェクトを作成します。

### パラメータ

`num`
  int もしくは string の値。 `num` が int の場合、BcMath\Number::scale は常に `0` に設定されます。 `num` が string の場合、有効な BCMath 数値形式の文字列である必要があり、 BcMath\Number::scale は自動的に文字列を解析して設定されます。

### エラー / 例外

このメソッドは、 `num` が string であり、BCMath で有効でない 数値形式の文字列である場合、ValueError をスローします。

### 例

例1 BcMath\Number::__construct() の例

    <?php
    $num1 = new BcMath\Number(100);
    $num2 = new BcMath\Number('-200');
    $num3 = new BcMath\Number('300.00');

    var_dump($num1, $num2, $num3);
    ?>

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

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "100"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(4) "-200"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(6) "300.00"
      ["scale"]=>
      int(2)
    }

### 参考

- BcMath\Number::__serialize() - BcMath\Number オブジェクトをシリアライズする
- BcMath\Number::__unserialize() - data 引数を BcMath\Number オブジェクトとして復元する

# BcMath\Number::div

(PHP 8 >= 8.4.0)

BcMath\Number::div — 任意精度数値の除算を行う

### 説明

public function BcMath\Number::div(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

$this を `num` で割ります。

### パラメータ

`num`
  除数を表す値。
`scale`
  計算結果オブジェクトの BcMath\Number::scale を明示的に指定します。 `null` の場合、計算結果の BcMath\Number::scale は自動的に設定されます。

### 戻り値

除算結果を新しい BcMath\Number オブジェクトとして返します。

除算結果オブジェクトの BcMath\Number::scale が自動的に設定される場合、被除数の BcMath\Number::scale が使用されます。ただし、割り切れない除算の場合は、 除算結果オブジェクトの BcMath\Number::scale が拡張されます。 拡張は必要に応じてのみ行われ、最大で `+10` まで拡張されます。

つまり、被除数の BcMath\Number::scale が `5` の場合、 除算結果オブジェクトの BcMath\Number::scale は `5` から `15` の間になります。

割り切れない除算の場合でも、除算結果オブジェクトの BcMath\Number::scale は常に `+10` まで拡張されるわけではありません。 末尾が `0` である場合は拡張の必要がないと見なされるため、 BcMath\Number::scale はその分だけ少なくなります。 また、最終的な BcMath\Number::scale は、拡張前の BcMath\Number::scale よりも小さくなることはありません。 コード例 も参照してください。

### エラー / 例外

このメソッドは、以下の場合に ValueError をスローします:

- `num` が、BCMath で有効でない数値形式の文字列である場合
- `scale` が範囲外の値である場合
- 結果オブジェクトの BcMath\Number::scale が範囲外の値である場合

このメソッドは、 `num` が `0` である場合、 DivisionByZeroError 例外をスローします。

### 例

例1 BcMath\Number::div() で `scale` を指定しない例

    <?php
    $number = new BcMath\Number('0.002');

    $ret1 = $number->div(new BcMath\Number('2.000'));
    $ret2 = $number->div('-3');
    $ret3 = $number->div(32);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

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

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "0.002"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(5) "0.001"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(16) "-0.0006666666666"
      ["scale"]=>
      int(13)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(9) "0.0000625"
      ["scale"]=>
      int(7)
    }

例2 BcMath\Number::div() で `scale` を指定する例

    <?php
    $number = new BcMath\Number('0.002');

    $ret1 = $number->div(new BcMath\Number('2.000'), 15);
    $ret2 = $number->div('-3', 5);
    $ret3 = $number->div(32, 2);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

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

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "0.002"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(17) "0.001000000000000"
      ["scale"]=>
      int(15)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(8) "-0.00066"
      ["scale"]=>
      int(5)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(4) "0.00"
      ["scale"]=>
      int(2)
    }

例3 BcMath\Number::div() の結果の BcMath\Number::scale が拡張される例

    <?php
    var_dump(
        new BcMath\Number('0.001')->div('10001'),
        new BcMath\Number('0.001')->div('10001', 13),
        new BcMath\Number('0.001')->div('100000000000001'),
    );
    ?>

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

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(13) "0.00000009999"
      ["scale"]=>
      int(11)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(15) "0.0000000999900"
      ["scale"]=>
      int(13)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "0.000"
      ["scale"]=>
      int(3)
    }

### 参考

- bcdiv() - 2つの任意精度数値で除算を行う
- BcMath\Number::divmod() - 任意精度数値の商と剰余を取得する
- BcMath\Number::mod() - 任意精度数値の剰余を取得する
- BcMath\Number::sqrt() - 任意精度数値の平方根を取得する
- BcMath\Number::pow() - 任意精度数値をべき乗する
- BcMath\Number::mul() - 任意精度数値の乗算を行う

# BcMath\Number::divmod

(PHP 8 >= 8.4.0)

BcMath\Number::divmod — 任意精度数値の商と剰余を取得する

### 説明

public function BcMath\Number::divmod(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): array

$this を `num` で割った商と剰余を取得します。

### パラメータ

`num`
  除数を表す値。
`scale`
  計算結果オブジェクトの BcMath\Number::scale を明示的に指定します。 `null` の場合、計算結果の BcMath\Number::scale は自動的に設定されます。

### 戻り値

1つ目の要素に商として新しい BcMath\Number オブジェクトが、 2つ目の要素に剰余として新しい BcMath\Number オブジェクトが格納された配列を返します。

商は常に整数値となるため、商オブジェクトの BcMath\Number::scale は `scale` の指定に関わらず、常に `0` になります。

`scale` を明示的に指定した場合、剰余オブジェクトの BcMath\Number::scale は指定された値になります。 剰余オブジェクトの BcMath\Number::scale が自動的に設定される場合、計算に使用された2つの数値のうち、大きい方の BcMath\Number::scale が使用されます。

つまり、2つの値の BcMath\Number::scale がそれぞれ `2` と `5` の場合、 剰余オブジェクトの BcMath\Number::scale は `5` になります。

### エラー / 例外

このメソッドは、以下の場合に ValueError をスローします:

- `num` が、BCMath で有効でない数値形式の文字列である場合
- `scale` が範囲外の値である場合

このメソッドは、 `num` が `0` である場合、 DivisionByZeroError 例外をスローします。

### 例

例1 BcMath\Number::divmod() で `scale` を指定しない例

    <?php
    echo '8.3 / 2.22' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('8')->divmod(new BcMath\Number('2.22'));
    var_dump($quot, $rem);

    echo PHP_EOL . '8.3 / 8.3' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('8.3')->divmod('8.3');
    var_dump($quot, $rem);

    echo PHP_EOL . '10 / -3' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('10')->divmod(-3);
    var_dump($quot, $rem);
    ?>

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

    8.3 / 2.22
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(4) "1.34"
      ["scale"]=>
      int(2)
    }

    8.3 / 8.3
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(3) "0.0"
      ["scale"]=>
      int(1)
    }

    10 / -3
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(2) "-3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }

例2 BcMath\Number::divmod() で `scale` を指定する例

    <?php
    echo '8.3 / 2.22' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('8')->divmod(new BcMath\Number('2.22'), 1);
    var_dump($quot, $rem);

    echo PHP_EOL . '8.3 / 8.3' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('8.3')->divmod('8.3', 4);
    var_dump($quot, $rem);

    echo PHP_EOL . '10 / -3' . PHP_EOL;
    [$quot, $rem] = new BcMath\Number('10')->divmod(-3, 5);
    var_dump($quot, $rem);
    ?>

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

    8.3 / 2.22
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.3"
      ["scale"]=>
      int(1)
    }

    8.3 / 8.3
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(6) "0.0000"
      ["scale"]=>
      int(4)
    }

    10 / -3
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(2) "-3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(7) "1.00000"
      ["scale"]=>
      int(5)
    }

### 参考

- bcdivmod() - 任意精度数値の商と剰余を取得する
- BcMath\Number::div() - 任意精度数値の除算を行う
- BcMath\Number::mod() - 任意精度数値の剰余を取得する

# BcMath\Number::floor

(PHP 8 >= 8.4.0)

BcMath\Number::floor — 任意精度数値を切り下げる

### 説明

public function BcMath\Number::floor(): BcMath\Number

必要に応じて $this を切り下げ、 $this の次に小さい整数値を返します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

結果を新しい BcMath\Number オブジェクトとして返します。 結果の BcMath\Number::scale は常に `0` になります。

### 例

例1 BcMath\Number::floor() の例

    <?php
    $num1 = new BcMath\Number('4.3')->floor();
    $num2 = new BcMath\Number('9.999')->floor();
    $num3 = new BcMath\Number('-3.14')->floor();

    var_dump($num1, $num2, $num3);
    ?>

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

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "4"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(2) "-4"
      ["scale"]=>
      int(0)
    }

### 参考

- bcfloor() - 任意精度数値を切り下げる
- BcMath\Number::ceil() - 任意精度数値を切り上げる
- BcMath\Number::round() - 任意精度数値を丸める

# BcMath\Number::mod

(PHP 8 >= 8.4.0)

BcMath\Number::mod — 任意精度数値の剰余を取得する

### 説明

public function BcMath\Number::mod(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

$this を `num` で割った剰余を取得します。 `num` が `0` でない限り、 結果は $this と同じ符号になります。

### パラメータ

`num`
  除数を表す値。
`scale`
  計算結果オブジェクトの BcMath\Number::scale を明示的に指定します。 `null` の場合、計算結果の BcMath\Number::scale は自動的に設定されます。

### 戻り値

剰余オブジェクトを新しい BcMath\Number オブジェクトとして返します。

剰余オブジェクトの BcMath\Number::scale が自動的に設定される場合、剰余計算に使用する2つの数値のうち、 大きい方の BcMath\Number::scale が使用されます。

つまり、2つの値の BcMath\Number::scale がそれぞれ `2` と `5` の場合、 加算結果オブジェクトの BcMath\Number::scale は `5` になります。

### エラー / 例外

このメソッドは、以下の場合に ValueError をスローします:

- `num` が、BCMath で有効でない数値形式の文字列である場合
- `scale` が範囲外の値である場合

このメソッドは、 `num` が `0` である場合、 DivisionByZeroError 例外をスローします。

### 例

例1 BcMath\Number::mod() で `scale` を指定しない例

    <?php
    $number = new BcMath\Number('8.3');

    $ret1 = $number->mod(new BcMath\Number('2.22'));
    $ret2 = $number->mod('8.3');
    $ret3 = $number->mod(-5);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

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

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "8.3"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(4) "1.64"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(3) "0.0"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "3.3"
      ["scale"]=>
      int(1)
    }

例2 BcMath\Number::mod() で `scale` を指定する例

    <?php
    $number = new BcMath\Number('8.3');

    $ret1 = $number->mod(new BcMath\Number('2.22'), 1);
    $ret2 = $number->mod('8.3', 3);
    $ret3 = $number->mod(-5, 0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

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

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "8.3"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(5) "0.000"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "3"
      ["scale"]=>
      int(0)
    }

### 参考

- bcmod() - 2 つの任意精度数値の剰余を取得する
- BcMath\Number::div() - 任意精度数値の除算を行う
- BcMath\Number::divmod() - 任意精度数値の商と剰余を取得する
- BcMath\Number::powmod() - 任意精度数値のべき乗の、指定した数値による剰余

# BcMath\Number::mul

(PHP 8 >= 8.4.0)

BcMath\Number::mul — 任意精度数値の乗算を行う

### 説明

public function BcMath\Number::mul(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

$this に `num` を掛けます。

### パラメータ

`num`
  乗数を表す値。
`scale`
  計算結果オブジェクトの BcMath\Number::scale を明示的に指定します。 `null` の場合、計算結果の BcMath\Number::scale は自動的に設定されます。

### 戻り値

乗算結果を新しい BcMath\Number オブジェクトとして返します。

乗算結果オブジェクトの BcMath\Number::scale が自動的に設定される場合、乗算に使用する2つの数値の BcMath\Number::scale の合計値が使用されます。

つまり、2つの値の BcMath\Number::scale がそれぞれ `2` と `5` の場合、 乗算結果オブジェクトの BcMath\Number::scale は `7` になります。

### エラー / 例外

このメソッドは、以下の場合に ValueError をスローします:

- `num` が、BCMath で有効でない数値形式の文字列である場合
- `scale` が範囲外の値である場合
- 結果オブジェクトの BcMath\Number::scale が範囲外の値である場合

### 例

例1 BcMath\Number::mul() で `scale` を指定しない例

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->mul(new BcMath\Number('2.3456'));
    $ret2 = $number->mul('-3.4');
    $ret3 = $number->mul(7);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

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

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(9) "2.8944704"
      ["scale"]=>
      int(7)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(7) "-4.1956"
      ["scale"]=>
      int(4)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "8.638"
      ["scale"]=>
      int(3)
    }

例2 BcMath\Number::mul() で `scale` を指定する例

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->mul(new BcMath\Number('2.3456'), 1);
    $ret2 = $number->mul('-3.4', 10);
    $ret3 = $number->mul(7, 0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

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

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "2.8"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(13) "-4.1956000000"
      ["scale"]=>
      int(10)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }

### 参考

- bcmul() - 2つの任意精度数値の乗算を行う
- BcMath\Number::div() - 任意精度数値の除算を行う
- BcMath\Number::pow() - 任意精度数値をべき乗する
- BcMath\Number::powmod() - 任意精度数値のべき乗の、指定した数値による剰余

# BcMath\Number::pow

(PHP 8 >= 8.4.0)

BcMath\Number::pow — 任意精度数値をべき乗する

### 説明

public function BcMath\Number::pow(BcMath\Number|string|int `$exponent`, ?int `$scale` = `null`): BcMath\Number

$this の `exponent` 乗を求めます。

### パラメータ

`exponent`
  指数を表す値。整数値でなければなりません。 `exponent` の有効な範囲はプラットフォームに依存しますが、少なくとも `-2147483648` から `2147483647` までの範囲を持ちます。
`scale`
  計算結果オブジェクトの BcMath\Number::scale を明示的に指定します。 `null` の場合、計算結果の BcMath\Number::scale は自動的に設定されます。

### 戻り値

べき乗の結果を新しい BcMath\Number オブジェクトとして返します。

べき乗結果オブジェクトの BcMath\Number::scale が自動的に設定される場合、 `exponent` の値に応じて、結果の BcMath\Number::scale が以下のようになります:

`exponent` | べき乗結果オブジェクトの BcMath\Number::scale
--- | ---
正の値 | (基数の BcMath\Number::scale) * (`exponent` の値)
`0` | `0`
負の値 | (基数の BcMath\Number::scale) と (基数の BcMath\Number::scale + `10`) の間

負の `exponent` を指定し割り切れない除算が発生した場合、べき乗結果オブジェクトの BcMath\Number::scale が拡張されます。拡張は必要な場合にのみ行われ、最大で `+10` まで拡張されます。 この動作は BcMath\Number::div() と同じですので、詳しくはそちらを参照して下さい。

### エラー / 例外

このメソッドは、以下の場合に ValueError をスローします:

- `exponent` が、BCMath で有効でない数値形式の文字列である場合
- `exponent` が整数値でない場合
- `exponent` もしくは `scale` が範囲外の値である場合
- 結果オブジェクトの BcMath\Number::scale が範囲外の値である場合

このメソッドは、$this の値が `0` かつ `exponent` が負の値である場合、 DivisionByZeroError 例外をスローします。

### 例

例1 BcMath\Number::pow() で `scale` を指定しない例

    <?php
    $number = new BcMath\Number('3.0');

    $ret1 = $number->pow(new BcMath\Number('5'));
    $ret2 = $number->pow('-1');
    $ret3 = $number->pow(0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

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

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "3.0"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(9) "243.00000"
      ["scale"]=>
      int(5)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(13) "0.33333333333"
      ["scale"]=>
      int(11)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }

例2 BcMath\Number::pow() で `scale` を指定する例

    <?php
    $number = new BcMath\Number('3.0');

    $ret1 = $number->pow(new BcMath\Number('5'), 0);
    $ret2 = $number->pow('-1', 2);
    $ret3 = $number->pow(0, 10);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

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

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(3) "3.0"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "243"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(4) "0.33"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(12) "1.0000000000"
      ["scale"]=>
      int(10)
    }

### 参考

- bcpow() - 任意精度数値をべき乗する
- BcMath\Number::powmod() - 任意精度数値のべき乗の、指定した数値による剰余
- BcMath\Number::mul() - 任意精度数値の乗算を行う
- BcMath\Number::sqrt() - 任意精度数値の平方根を取得する
- BcMath\Number::div() - 任意精度数値の除算を行う

# BcMath\Number::powmod

(PHP 8 >= 8.4.0)

BcMath\Number::powmod — 任意精度数値のべき乗の、指定した数値による剰余

### 説明

public function BcMath\Number::powmod(BcMath\Number|string|int `$exponent`, BcMath\Number|string|int `$modulus`, ?int `$scale` = `null`): BcMath\Number

`modulus` で割った余りを求めることを考慮して、 $this の `exponent` 乗を高速に計算します。

### パラメータ

`exponent`
  基数を表す整数の値。 (つまり、scale は 0 でなければいけません)
`modulus`
  指数を表す、負でない、整数の値。 (つまり、scale は 0 でなければいけません)
`scale`
  計算結果オブジェクトの BcMath\Number::scale を明示的に指定します。 `null` の場合、計算結果の BcMath\Number::scale は自動的に設定されます。

### 戻り値

計算結果を新しい BcMath\Number オブジェクトとして返します。

計算結果オブジェクトの BcMath\Number::scale が自動的に設定される場合、常に `0` になります。

### エラー / 例外

このメソッドは、以下の場合に ValueError をスローします:

- `exponent` もしくは `modulus` が、BCMath で有効でない数値形式の文字列である場合
- $this か `exponent` か `modulus` のうち、どれか一つでも整数値でない場合
- `exponent` が負の値である場合
- `scale` が範囲外の値である場合

このメソッドは、 `modulus` が `0` である場合、 DivisionByZeroError 例外をスローします。

### 例

例1 BcMath\Number::powmod() で `scale` を指定しない例

    <?php
    var_dump(
        new BcMath\Number('8')->powmod(new BcMath\Number('3'), 5),
        new BcMath\Number('-8')->powmod(new BcMath\Number('3'), 5),
        new BcMath\Number('8')->powmod('2', -3),
        new BcMath\Number('-8')->powmod(5, 7),
    );
    ?>

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

    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "2"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(2) "-2"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "1"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(2) "-1"
      ["scale"]=>
      int(0)
    }

例2 BcMath\Number::powmod() で `scale` を指定する例

    <?php
    var_dump(
        new BcMath\Number('8')->powmod(new BcMath\Number('3'), 5, 1),
        new BcMath\Number('-8')->powmod(new BcMath\Number('3'), 5, 2),
        new BcMath\Number('8')->powmod('2', -3, 3),
        new BcMath\Number('-8')->powmod(5, 7, 4),
    );
    ?>

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

    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(3) "2.0"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "-2.00"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(5) "1.000"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(7) "-1.0000"
      ["scale"]=>
      int(4)
    }

### 参考

- bcpowmod() - 任意精度数値のべき乗の、指定した数値による剰余
- BcMath\Number::pow() - 任意精度数値をべき乗する
- BcMath\Number::mod() - 任意精度数値の剰余を取得する

# BcMath\Number::round

(PHP 8 >= 8.4.0)

BcMath\Number::round — 任意精度数値を丸める

### 説明

public function BcMath\Number::round(int `$precision` = 0, RoundingMode `$mode` = `RoundingMode::HalfAwayFromZero`): BcMath\Number

$this を、指定した `precision`(小数点以下の桁数)に丸めた値を返します。 `precision` を負またはゼロ(デフォルト) とすることも可能です。

### パラメータ

`precision`

  オプションで指定する、丸める桁数。

  `precision` が正の値の場合、 `num` は 小数点以下、有効桁数 `precision` 桁に丸められます。

  `precision` が負の場合、 `num` の 丸め処理は小数点より前の `precision` 桁に対して行われます。 つまり、一番近い `pow(10, -$precision)` の倍数に丸められます。 たとえば、`precision` が -1 の場合、 `num` は 一番近い10の倍数に、 `precision` が -2 の場合は 一番近い100の倍数に丸められる、という具合です。

`mode`
  指定する丸めモード。詳しくは RoundingMode を参照してください。

### 戻り値

結果を新しい BcMath\Number オブジェクトとして返します。

### エラー / 例外

このメソッドは、無効な `mode` が指定された場合に ValueError をスローします。

### 例

例1 BcMath\Number::round() の例

    <?php
    var_dump(
        new BcMath\Number('3.4')->round(),
        new BcMath\Number('3.5')->round(),
        new BcMath\Number('3.6')->round(),
        new BcMath\Number('3.6')->round(0),
        new BcMath\Number('5.045')->round(2),
        new BcMath\Number('5.055')->round(2),
        new BcMath\Number('345')->round(-2),
        new BcMath\Number('345')->round(-3),
        new BcMath\Number('678')->round(-2),
        new BcMath\Number('678')->round(-3),
    );
    ?>

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

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(1) "3"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "4"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "4"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(1) "4"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#6 (2) {
      ["value"]=>
      string(4) "5.05"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(4) "5.06"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#8 (2) {
      ["value"]=>
      string(3) "300"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#9 (2) {
      ["value"]=>
      string(1) "0"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#10 (2) {
      ["value"]=>
      string(3) "700"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#11 (2) {
      ["value"]=>
      string(4) "1000"
      ["scale"]=>
      int(0)
    }

例2 BcMath\Number::round() で異なる `precision` を指定した例

    <?php
    $number = new BcMath\Number('123.45');

    var_dump(
        $number->round(3),
        $number->round(2),
        $number->round(1),
        $number->round(0),
        $number->round(-1),
        $number->round(-2),
        $number->round(-3),
    );
    ?>

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

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(7) "123.450"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(6) "123.45"
      ["scale"]=>
      int(2)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(5) "123.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(3) "123"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#6 (2) {
      ["value"]=>
      string(3) "120"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(3) "100"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#8 (2) {
      ["value"]=>
      string(1) "0"
      ["scale"]=>
      int(0)
    }

例3 BcMath\Number::round() で異なる `mode` を指定した例

    <?php
    echo 'Rounding modes with 9.5' . PHP_EOL;
    $number = new BcMath\Number('9.5');
    var_dump(
        $number->round(0, RoundingMode::HalfAwayFromZero),
        $number->round(0, RoundingMode::HalfTowardsZero),
        $number->round(0, RoundingMode::HalfEven),
        $number->round(0, RoundingMode::HalfOdd),
        $number->round(0, RoundingMode::TowardsZero),
        $number->round(0, RoundingMode::AwayFromZero),
        $number->round(0, RoundingMode::NegativeInfinity),
        $number->round(0, RoundingMode::PositiveInfinity),
    );

    echo PHP_EOL;
    echo 'Rounding modes with 8.5' . PHP_EOL;
    $number = new BcMath\Number('8.5');
    var_dump(
        $number->round(0, RoundingMode::HalfAwayFromZero),
        $number->round(0, RoundingMode::HalfTowardsZero),
        $number->round(0, RoundingMode::HalfEven),
        $number->round(0, RoundingMode::HalfOdd),
        $number->round(0, RoundingMode::TowardsZero),
        $number->round(0, RoundingMode::AwayFromZero),
        $number->round(0, RoundingMode::NegativeInfinity),
        $number->round(0, RoundingMode::PositiveInfinity),
    );
    ?>

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

    Rounding modes with 9.5
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#9 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#11 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#13 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#15 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#17 (2) {
      ["value"]=>
      string(2) "10"
      ["scale"]=>
      int(0)
    }

    Rounding modes with 8.5
    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#15 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#13 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#11 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#9 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(1) "8"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(1) "9"
      ["scale"]=>
      int(0)
    }

例4 BcMath\Number::round() で `precision` を指定し、 異なる `mode` を指定した例

    <?php
    $positive = new BcMath\Number('1.55');
    $negative = new BcMath\Number('-1.55');

    echo 'Using RoundingMode::HalfAwayFromZero with 1 decimal digit precision' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::HalfAwayFromZero),
        $negative->round(1, RoundingMode::HalfAwayFromZero),
    );

    echo PHP_EOL;
    echo 'Using RoundingMode::HalfTowardsZero with 1 decimal digit precision' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::HalfTowardsZero),
        $negative->round(1, RoundingMode::HalfTowardsZero),
    );

    echo PHP_EOL;
    echo 'Using RoundingMode::HalfEven with 1 decimal digit precision' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::HalfEven),
        $negative->round(1, RoundingMode::HalfEven),
    );

    echo PHP_EOL;
    echo 'Using RoundingMode::HalfOdd with 1 decimal digit precision' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::HalfOdd),
        $negative->round(1, RoundingMode::HalfOdd),
    );

    echo PHP_EOL;
    echo 'Using RoundingMode::TowardsZero with 1 decimal digit precision' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::TowardsZero),
        $negative->round(1, RoundingMode::TowardsZero),
    );

    echo PHP_EOL;
    echo 'Using RoundingMode::AwayFromZero with 1 decimal digit precision' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::AwayFromZero),
        $negative->round(1, RoundingMode::AwayFromZero),
    );

    echo PHP_EOL;
    echo 'Using RoundingMode::NegativeInfinity with 1 decimal digit precision' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::NegativeInfinity),
        $negative->round(1, RoundingMode::NegativeInfinity),
    );

    echo PHP_EOL;
    echo 'Using RoundingMode::PositiveInfinity with 1 decimal digit precision' . PHP_EOL;
    var_dump(
        $positive->round(1, RoundingMode::PositiveInfinity),
        $negative->round(1, RoundingMode::PositiveInfinity),
    );
    ?>

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

    Using RoundingMode::HalfAwayFromZero with 1 decimal digit precision
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(4) "-1.6"
      ["scale"]=>
      int(1)
    }

    Using RoundingMode::HalfTowardsZero with 1 decimal digit precision
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#6 (2) {
      ["value"]=>
      string(4) "-1.5"
      ["scale"]=>
      int(1)
    }

    Using RoundingMode::HalfEven with 1 decimal digit precision
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#7 (2) {
      ["value"]=>
      string(4) "-1.6"
      ["scale"]=>
      int(1)
    }

    Using RoundingMode::HalfOdd with 1 decimal digit precision
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#8 (2) {
      ["value"]=>
      string(4) "-1.5"
      ["scale"]=>
      int(1)
    }

    Using RoundingMode::TowardsZero with 1 decimal digit precision
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#9 (2) {
      ["value"]=>
      string(4) "-1.5"
      ["scale"]=>
      int(1)
    }

    Using RoundingMode::AwayFromZero with 1 decimal digit precision
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#10 (2) {
      ["value"]=>
      string(4) "-1.6"
      ["scale"]=>
      int(1)
    }

    Using RoundingMode::NegativeInfinity with 1 decimal digit precision
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.5"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#11 (2) {
      ["value"]=>
      string(4) "-1.6"
      ["scale"]=>
      int(1)
    }

    Using RoundingMode::PositiveInfinity with 1 decimal digit precision
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(3) "1.6"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#12 (2) {
      ["value"]=>
      string(4) "-1.5"
      ["scale"]=>
      int(1)
    }

### 参考

- bcround() - 任意精度数値を丸める
- BcMath\Number::ceil() - 任意精度数値を切り上げる
- BcMath\Number::floor() - 任意精度数値を切り下げる

# BcMath\Number::__serialize

(PHP 8 >= 8.4.0)

BcMath\Number::__serialize — BcMath\Number オブジェクトをシリアライズする

### 説明

public function BcMath\Number::__serialize(): array

$this をシリアライズします。

### パラメータ

この関数にはパラメータはありません。

### 参考

- BcMath\Number::__construct() - BcMath\Number オブジェクトを作成する
- BcMath\Number::__unserialize() - data 引数を BcMath\Number オブジェクトとして復元する

# BcMath\Number::sqrt

(PHP 8 >= 8.4.0)

BcMath\Number::sqrt — 任意精度数値の平方根を取得する

### 説明

public function BcMath\Number::sqrt(?int `$scale` = `null`): BcMath\Number

$this の平方根を返します。

### パラメータ

`scale`
  計算結果オブジェクトの BcMath\Number::scale を明示的に指定します。 `null` の場合、計算結果の BcMath\Number::scale は自動的に設定されます。

### 戻り値

平方根を新しい BcMath\Number オブジェクトとして返します。

計算結果オブジェクトの BcMath\Number::scale が自動的に設定される場合、$this の BcMath\Number::scale が使用されます。ただし、割り切れない除算が発生した場合は、 計算結果オブジェクトの BcMath\Number::scale が拡張されます。 拡張は必要に応じてのみ行われ、最大で `+10` まで拡張されます。 この動作は BcMath\Number::div() と同じですので、詳しくはそちらを参照して下さい。

つまり、$this の BcMath\Number::scale が `5` の場合、 計算結果オブジェクトの BcMath\Number::scale は `5` から `15` の間になります。

### エラー / 例外

このメソッドは、以下の場合に ValueError をスローします:

- $this が負の値である場合
- `scale` が範囲外の値である場合
- 結果オブジェクトの BcMath\Number::scale が範囲外の値である場合

### 例

例1 BcMath\Number::sqrt() の例

    <?php
    var_dump(
        new BcMath\Number('2')->sqrt(),
        new BcMath\Number('2')->sqrt(3),
        new BcMath\Number('4')->sqrt(),
        new BcMath\Number('4')->sqrt(3),
    );
    ?>

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

    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(12) "1.4142135623"
      ["scale"]=>
      int(10)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(5) "1.414"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(1) "2"
      ["scale"]=>
      int(0)
    }
    object(BcMath\Number)#5 (2) {
      ["value"]=>
      string(5) "2.000"
      ["scale"]=>
      int(3)
    }

### 参考

- bcsqrt() - 任意精度数値の平方根を取得する
- BcMath\Number::div() - 任意精度数値の除算を行う
- BcMath\Number::pow() - 任意精度数値をべき乗する

# BcMath\Number::sub

(PHP 8 >= 8.4.0)

BcMath\Number::sub — 任意精度数値の減算を行う

### 説明

public function BcMath\Number::sub(BcMath\Number|string|int `$num`, ?int `$scale` = `null`): BcMath\Number

$this と `num` を減算します。

### パラメータ

`num`
  減数を表す値。
`scale`
  計算結果オブジェクトの BcMath\Number::scale を明示的に指定します。 `null` の場合、計算結果の BcMath\Number::scale は自動的に設定されます。

### 戻り値

減算結果を新しい BcMath\Number オブジェクトとして返します。

減算結果オブジェクトの BcMath\Number::scale が自動的に設定される場合、減算に使用する2つの数値のうち、 大きい方の BcMath\Number::scale が使用されます。

つまり、2つの値の BcMath\Number::scale がそれぞれ `2` と `5` の場合、 加算結果オブジェクトの BcMath\Number::scale は `5` になります。

### エラー / 例外

このメソッドは、以下の場合に ValueError をスローします:

- `num` が、BCMath で有効でない数値形式の文字列である場合
- `scale` が範囲外の値である場合

### 例

例1 BcMath\Number::sub() で `scale` を指定しない例

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->sub(new BcMath\Number('2.34567'));
    $ret2 = $number->sub('-3.456');
    $ret3 = $number->sub(7);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

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

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(8) "-1.11167"
      ["scale"]=>
      int(5)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(5) "4.690"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(6) "-5.766"
      ["scale"]=>
      int(3)
    }

例2 BcMath\Number::sub() で `scale` を指定する例

    <?php
    $number = new BcMath\Number('1.234');

    $ret1 = $number->sub(new BcMath\Number('2.34567'), 1);
    $ret2 = $number->sub('-3.456', 10);
    $ret3 = $number->sub(7, 0);

    var_dump($number, $ret1, $ret2, $ret3);
    ?>

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

    object(BcMath\Number)#1 (2) {
      ["value"]=>
      string(5) "1.234"
      ["scale"]=>
      int(3)
    }
    object(BcMath\Number)#3 (2) {
      ["value"]=>
      string(4) "-1.1"
      ["scale"]=>
      int(1)
    }
    object(BcMath\Number)#2 (2) {
      ["value"]=>
      string(12) "4.6900000000"
      ["scale"]=>
      int(10)
    }
    object(BcMath\Number)#4 (2) {
      ["value"]=>
      string(2) "-5"
      ["scale"]=>
      int(0)
    }

### 参考

- bcsub() - 任意精度数値の減算を行う
- BcMath\Number::add() - 任意精度の数値を加算する

# BcMath\Number::__toString

(PHP 8 >= 8.4.0)

BcMath\Number::__toString — BcMath\Number オブジェクトを文字列に変換する

### 説明

public function BcMath\Number::__toString(): string

BcMath\Number を string に変換します。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

BcMath\Number::value を string として返します。

# BcMath\Number::__unserialize

(PHP 8 >= 8.4.0)

BcMath\Number::__unserialize — data 引数を BcMath\Number オブジェクトとして復元する

### 説明

public function BcMath\Number::__unserialize(array `$data`): void

data 引数を BcMath\Number オブジェクトとして復元します。

### パラメータ

`data`
  連想配列としてシリアライズされたデータ。

### エラー / 例外

このメソッドは、不正なシリアライズデータが渡された場合、ValueError をスローします。

### 参考

- BcMath\Number::__construct() - BcMath\Number オブジェクトを作成する
- BcMath\Number::serialize()

## 目次

- BcMath\Number::add — 任意精度の数値を加算する
- BcMath\Number::ceil — 任意精度数値を切り上げる
- BcMath\Number::compare — 任意精度数値を比較する
- BcMath\Number::__construct — BcMath\Number オブジェクトを作成する
- BcMath\Number::div — 任意精度数値の除算を行う
- BcMath\Number::divmod — 任意精度数値の商と剰余を取得する
- BcMath\Number::floor — 任意精度数値を切り下げる
- BcMath\Number::mod — 任意精度数値の剰余を取得する
- BcMath\Number::mul — 任意精度数値の乗算を行う
- BcMath\Number::pow — 任意精度数値をべき乗する
- BcMath\Number::powmod — 任意精度数値のべき乗の、指定した数値による剰余
- BcMath\Number::round — 任意精度数値を丸める
- BcMath\Number::__serialize — BcMath\Number オブジェクトをシリアライズする
- BcMath\Number::sqrt — 任意精度数値の平方根を取得する
- BcMath\Number::sub — 任意精度数値の減算を行う
- BcMath\Number::__toString — BcMath\Number オブジェクトを文字列に変換する
- BcMath\Number::__unserialize — data 引数を BcMath\Number オブジェクトとして復元する

- インストール/設定
  - インストール手順
  - 実行時設定
- BC Math 関数
  - bcadd — 2つの任意精度の数値を加算する
  - bcceil — 任意精度数値を切り上げる
  - bccomp — 2 つの任意精度数値を比較する
  - bcdiv — 2つの任意精度数値で除算を行う
  - bcdivmod — 任意精度数値の商と剰余を取得する
  - bcfloor — 任意精度数値を切り下げる
  - bcmod — 2 つの任意精度数値の剰余を取得する
  - bcmul — 2つの任意精度数値の乗算を行う
  - bcpow — 任意精度数値をべき乗する
  - bcpowmod — 任意精度数値のべき乗の、指定した数値による剰余
  - bcround — 任意精度数値を丸める
  - bcscale — すべての BC 演算関数におけるデフォルトのスケールを設定/取得する
  - bcsqrt — 任意精度数値の平方根を取得する
  - bcsub — 任意精度数値の減算を行う
- BcMath\Number — BcMath\Number クラス
  - BcMath\Number::add — 任意精度の数値を加算する
  - BcMath\Number::ceil — 任意精度数値を切り上げる
  - BcMath\Number::compare — 任意精度数値を比較する
  - BcMath\Number::__construct — BcMath\Number オブジェクトを作成する
  - BcMath\Number::div — 任意精度数値の除算を行う
  - BcMath\Number::divmod — 任意精度数値の商と剰余を取得する
  - BcMath\Number::floor — 任意精度数値を切り下げる
  - BcMath\Number::mod — 任意精度数値の剰余を取得する
  - BcMath\Number::mul — 任意精度数値の乗算を行う
  - BcMath\Number::pow — 任意精度数値をべき乗する
  - BcMath\Number::powmod — 任意精度数値のべき乗の、指定した数値による剰余
  - BcMath\Number::round — 任意精度数値を丸める
  - BcMath\Number::__serialize — BcMath\Number オブジェクトをシリアライズする
  - BcMath\Number::sqrt — 任意精度数値の平方根を取得する
  - BcMath\Number::sub — 任意精度数値の減算を行う
  - BcMath\Number::__toString — BcMath\Number オブジェクトを文字列に変換する
  - BcMath\Number::__unserialize — data 引数を BcMath\Number オブジェクトとして復元する

# GNU Multiple Precision

# はじめに

以下の関数により、GNU MP ライブラリを使用して 任意長の整数を使用することが可能になります。

> 注意:

> 大半の GMP 関数は、GMP 数を引数としてとります。 このマニュアルでは、GMP 数を GMP オブジェクトとしています。 これらの関数の大半は、数値と文字列も 引数として指定可能です。ただし、後者は数値に変換できる場合に限ります。 また、整数引数を使用して処理を行うより高速な関数がある場合には、 指定された引数が整数である場合により低速となる関数の代わりに 使用されます。これは透過的に行われます。 gmp_init() も参照ください。

> 注意:

> gmp_init() やその他の GMP 関数が返す GMP オブジェクトに対して、 算術演算子や ビット演算子そして 比較演算子 が使えるようになります。

警告

より大きな整数を明示的に指定するには、文字列として指定する必要があります。 さもないと、PHP は値をまず float として解釈するので、 精度が劣化してしまいます。

# インストール/設定

## 目次

- 要件
- インストール手順

## 要件

» 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

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_abs — 絶対値

### 説明

function gmp_abs(GMP|int|string `$num`): GMP

ある数の絶対値を返します。

### パラメータ

`num`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

`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_add

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_add — 数値を加算する

### 説明

function gmp_add(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

2 つの数を加算します。

### パラメータ

`num1`
  足される数。 GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`num2`

  足す数。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

加算の結果を GMP 数で返します。

### 例

例1 gmp_add() の例

    <?php
    $sum = gmp_add("123456789012345", "76543210987655");
    echo gmp_strval($sum) . "\n";
    ?>

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

    200000000000000

# gmp_and

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_and — ビット AND を計算する

### 説明

function gmp_and(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

2 つの GMP 数のビット AND を計算します。

### パラメータ

`num1`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`num2`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

ビット `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_binomial

(PHP 7 >= 7.3.0, PHP 8)

gmp_binomial — 二項係数を計算する

### 説明

function gmp_binomial(GMP|int|string `$n`, int `$k`): GMP

二項係数 C(n, k) を計算します。

### パラメータ

`n`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`k`

### 戻り値

二項係数 C(n, k) を返します。

### エラー / 例外

`k` が負の場合、ValueError がスローされます。 PHP 8.0.0 より前のバージョンでは、E_WARNING レベルの警告が発生していました。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | この関数は、失敗時に `false` を返さなくなりました。

# gmp_clrbit

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_clrbit — ビットをクリアする

### 説明

function gmp_clrbit(GMP `$num`, int `$index`): void

`num` のビット `index` をクリア (0 に設定) します。index は 0 から始まります。

### パラメータ

`num`

  GMP オブジェクト

`index`

  クリアするビットのインデックス。0 が最下位ビットを表します。

### 戻り値

値を返しません。

### 例

例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_cmp

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_cmp — 数を比較する

### 説明

function gmp_cmp(GMP|int|string `$num1`, GMP|int|string `$num2`): int

ふたつの数を比較します。

### パラメータ

`num1`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`num2`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

`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

# gmp_com

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_com — 1 の補数を計算する

### 説明

function gmp_com(GMP|int|string `$num`): GMP

`num` について、1 の補数を返します。

### パラメータ

`num`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

`num` についての 1 の補数を GMP 数で返します。

### 例

例1 gmp_com() の例

    <?php
    $com = gmp_com("1234");
    echo gmp_strval($com) . "\n";
    ?>

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

    -1235

# gmp_div

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div — gmp_div_q() のエイリアス

### 説明

この関数は次の関数のエイリアスです。 gmp_div_q().

# gmp_div_q

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div_q — 数値を除算する

### 説明

function gmp_div_q(GMP|int|string `$num1`, GMP|int|string `$num2`, int `$rounding_mode` = `GMP_ROUND_ZERO`): GMP

`num1` を `num2` で割り、 結果を整数で返します。

### パラメータ

`num1`

  割られる数。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`num2`

  `num1` を割る数。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`rounding_mode`

  結果の丸め方は `rounding_mode` で指定し、次の値を指定可能です。

  - `GMP_ROUND_ZERO`: 結果は 0 の方に丸められます。
  - `GMP_ROUND_PLUSINF`: 結果は、 `+infinity` の方に丸められます。
  - `GMP_ROUND_MINUSINF`: 結果は、 `-infinity` の方に丸められます。
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

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_qr

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div_qr — 除算を行い、商と余りを得る

### 説明

function gmp_div_qr(GMP|int|string `$num1`, GMP|int|string `$num2`, int `$rounding_mode` = `GMP_ROUND_ZERO`): array

この関数は、`num1` を `num2` で割ります。

### パラメータ

`num1`

  割られる数。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`num2`

  `num1` を割る数。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`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_r

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_div_r — 除算の余りを計算する

### 説明

function gmp_div_r(GMP|int|string `$num1`, GMP|int|string `$num2`, int `$rounding_mode` = `GMP_ROUND_ZERO`): resource

`num1` を `num2` で整数として割った際の余りを計算します。余りは、引数 `num1` がゼロでない場合に、これと同じ符号を有します。

### パラメータ

`num1`

  割られる数。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`num2`

  `num1` を割る数。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`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_divexact

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_divexact — 正確な除算

### 説明

function gmp_divexact(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

高速な "exact division" アルゴリズムを使用して `num1` を `num2` で割ります。 この関数は、`num1` が `num2` で割り切れることがわかっている場合にのみ正確な結果を出力します。

### パラメータ

`num1`

  割られる数。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`num2`

  `num1` を割る数。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

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_export

(PHP 5 >= 5.6.1, PHP 7, PHP 8)

gmp_export — バイナリ文字列にエクスポートする

### 説明

function 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_fact

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_fact — 階乗

### 説明

function gmp_fact(GMP|int|string `$num`): GMP

`num` の階乗 (`num!`) を計算します。

### パラメータ

`num`

  階乗を求める数。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

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_gcd

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_gcd — 最大公約数を計算する

### 説明

function gmp_gcd(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

`num1` と `num2` の最大公約数を計算します。 引数のどちらかまたは両方が負の場合でも結果は常に正となります。

### パラメータ

`num1`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`num2`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

`num1` と `num2` の両方を割り切ることができる正の数を GMP 数で返します。

### 例

例1 gmp_gcd() の例

    <?php
    $gcd = gmp_gcd("12", "21");
    echo gmp_strval($gcd) . "\n";
    ?>

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

    3

### 参考

- gmp_lcm() - 最小公倍数を計算する

# gmp_gcdext

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_gcdext — 最大公約数と乗数を計算する

### 説明

function 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 オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`num2`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

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_hamdist

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_hamdist — ハミング距離

### 説明

function gmp_hamdist(GMP|int|string `$num1`, GMP|int|string `$num2`): int

`num1` と `num2` の間のハミング距離を返します。オペランドは共に非負とする必要があります。

### パラメータ

`num1`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

  正の数である必要があります。

`num2`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

  正の数である必要があります。

### 戻り値

`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_import

(PHP 5 >= 5.6.1, PHP 7, PHP 8)

gmp_import — バイナリ文字列からインポートする

### 説明

function 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_init

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_init — GMP 数を作成する

### 説明

function gmp_init(int|string `$num`, int `$base` = 0): GMP

整数または文字列から GMP 数を生成します。

### パラメータ

`num`
  整数値あるいは文字列。文字列表現には、 10進数か16進数か8進数、あるいは2進数を使用可能です。
`base`
  文字列表現を変換するのに使う基数 明示的に基数を指定する場合、 `2` から `62` までの値を指定できます。 `36` までの場合、大文字小文字は無視されます。 つまり、大文字だろうと小文字だろうと、同じ値だということです。 `37` から `62` までの場合、 大文字の値は `10` から `35` までの値を示し、小文字の値は `36` から `61` までの値を示します。 `base` を `0` にした場合、 実際の基数の解釈は `num` の先頭の文字によって決まります。 最初の2文字が `0x` や `0X` の場合、 文字列は16進数として解釈されます。 最初の2文字が `0b` や `0B` の場合、 文字列は2進数として解釈されます。 最初の2文字が `0o` や `0O` の場合、 文字列は8進数として解釈されます。 さらに、最初の文字が `0` の場合も、 文字列は8進数として解釈されます。 上記以外の場合は全て、文字列は10進数として解釈されます。

### 戻り値

GMP オブジェクトを返します。

### 変更履歴

バージョン | 説明
--- | ---
8.1.0 | `num` 文字列に、8進数を表すプレフィックス `0o` と `0O` を明示的に指定する機能をサポートしました。 `base` を `0` にした場合に、 こうしたプレフィックスを解釈する機能も追加されています。

### 例

例1 GMP 数の作成

    <?php
    $a = gmp_init(123456);
    $b = gmp_init("0xFFFFDEBACDFEDF7200");
    ?>

### 注意

> 注意:

> gmp_add() のような GMP 関数において、GMP 数を指定するところに整数または文字列を使用したい場合には、 この関数をコールする必要はありません。この場合、変換が必要な場合には、 gmp_init() と同様の方法で関数の引数は自動的に GMP 数に変換されます。

### 参考

- GMP::__construct() - GMP数を作成する

# gmp_intval

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_intval — GMP 数を整数に変換する

### 説明

function gmp_intval(GMP|int|string `$num`): int

この関数は、GMP 数を PHP ネイティブの整数に変換します。

### パラメータ

`num`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

`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_invert

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_invert — 法による逆

### 説明

function gmp_invert(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP|false

`num2` を法とした `num1` の逆を計算します。

### パラメータ

`num1`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`num2`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

成功した場合に GMP 数、逆が存在しない場合に `false` を返します。

### 例

例1 gmp_invert() の例

    <?php
    echo gmp_invert("5", "10"); // 逆は存在しないので何も出力せず、結果は FALSE となります
    $invert = gmp_invert("5", "11");
    echo gmp_strval($invert) . "\n";
    ?>

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

    9

# gmp_jacobi

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_jacobi — ヤコビ記号

### 説明

function gmp_jacobi(GMP|int|string `$num1`, GMP|int|string `$num2`): int

`num1` および `num2` の » ヤコビ記号 を計算します。`num2` は正の奇数である必要があります。

### パラメータ

`num1`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`num2`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

  正の奇数でなければなりません。

### 戻り値

GMP オブジェクトを返します。

### 例

例1 gmp_jacobi() の例

    <?php
    echo gmp_jacobi("1", "3") . "\n";
    echo gmp_jacobi("2", "3") . "\n";
    ?>

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

    1
    0

### 参考

- gmp_kronecker() - クロネッカーの記号を計算する
- gmp_legendre() - ルジェンドル記号

# gmp_kronecker

(PHP 7 >= 7.3.0, PHP 8)

gmp_kronecker — クロネッカーの記号を計算する

### 説明

function gmp_kronecker(GMP|int|string `$num1`, GMP|int|string `$num2`): int

この関数は `num1` と `num2` のクロネッカーの記号を計算します。

### パラメータ

`num1`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`num2`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

`num1` と `num2` のクロネッカーの記号を返します。

### 参考

- gmp_jacobi() - ヤコビ記号
- gmp_legendre() - ルジェンドル記号

# gmp_lcm

(PHP 7 >= 7.3.0, PHP 8)

gmp_lcm — 最小公倍数を計算する

### 説明

function gmp_lcm(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

この関数は、`num1` と `num2` の最小公倍数(lcm)を計算します。

### パラメータ

`num1`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`num2`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

GMP オブジェクトを返します。

### 参考

- gmp_gcd() - 最大公約数を計算する

# gmp_legendre

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_legendre — ルジェンドル記号

### 説明

function gmp_legendre(GMP|int|string `$num1`, GMP|int|string `$num2`): int

`num1` と `num2` の » ルジェンドル記号 を計算します。`num2` は、正の奇数である必要があります。

### パラメータ

`num1`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`num2`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

  正の奇数でなければなりません。

### 戻り値

GMP オブジェクトを返します。

### 例

例1 gmp_legendre() の例

    <?php
    echo gmp_legendre("1", "3") . "\n";
    echo gmp_legendre("2", "3") . "\n";
    ?>

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

    1
    0

### 参考

- gmp_jacobi() - ヤコビ記号
- gmp_kronecker() - クロネッカーの記号を計算する

# gmp_mod

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_mod — モジュロ演算

### 説明

function gmp_mod(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

`num2` を法とした `num1` を計算します。結果は常に非負であり、 `num2` の符号は無視されます。

### パラメータ

`num1`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`num2`

  法として使用する値。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

GMP オブジェクトを返します。

### 例

例1 gmp_mod() の例

    <?php
    $mod = gmp_mod("8", "3");
    echo gmp_strval($mod) . "\n";
    ?>

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

    2

# gmp_mul

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_mul — 数値を乗算する

### 説明

function gmp_mul(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

`num1` と `num2` をかけ、 結果を返します。

### パラメータ

`num1`

  `num2` を掛けられる数。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`num2`

  `num1` に掛ける数。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

GMP オブジェクトを返します。

### 例

例1 gmp_mul() の例

    <?php
    $mul = gmp_mul("12345678", "2000");
    echo gmp_strval($mul) . "\n";
    ?>

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

    24691356000

# gmp_neg

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_neg — 符号を反転する

### 説明

function gmp_neg(GMP|int|string `$num`): GMP

ある数の符号を反転したものを返します。

### パラメータ

`num`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

-`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_nextprime

(PHP 5 >= 5.2.0, PHP 7, PHP 8)

gmp_nextprime — 次の素数を見つける

### 説明

function gmp_nextprime(GMP|int|string `$num`): GMP

次の素数を見つけます。

### パラメータ

`num`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

`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

### 注意

> 注意:

> この関数は素数を識別するのに確率的アルゴリズムを使用します。 誤って合成数を取得してしまうことは、まずありません。

# gmp_or

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_or — ビット OR を計算する

### 説明

function gmp_or(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

2 つの GMP 数のビット OR を計算します。

### パラメータ

`num1`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`num2`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

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_perfect_power

(PHP 7 >= 7.3.0, PHP 8)

gmp_perfect_power — 累乗数かどうかを調べる

### 説明

function gmp_perfect_power(GMP|int|string `$num`): bool

`num` が累乗数かどうかを調べます。

### パラメータ

`num`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

`num` が累乗数であった場合は `true` を返し、 そうでない場合は `false` を返します。

### 参考

- gmp_perfect_square() - 平方数かどうかを調べる

# gmp_perfect_square

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_perfect_square — 平方数かどうかを調べる

### 説明

function gmp_perfect_square(GMP|int|string `$num`): bool

その数が平方数であるかどうかを調べます。

### パラメータ

`num`

  平方数かどうかを調べたい数。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

`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_popcount

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_popcount — セットされているビットの数

### 説明

function gmp_popcount(GMP|int|string `$num`): int

セットされているビットの数を返します。

### パラメータ

`num`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

`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_pow

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_pow — べき乗を計算する

### 説明

function gmp_pow(GMP|int|string `$num`, int `$exponent`): GMP

`num` の `exponent` 乗を計算します。

### パラメータ

`num`

  もととなる数。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`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_powm

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_powm — べき乗とモジュロを計算する

### 説明

function gmp_powm(GMP|int|string `$num`, GMP|int|string `$exponent`, GMP|int|string `$modulus`): GMP

`modulus` を法として (`num` の `exponent` 乗) を計算します。 `exponent` が負の場合、結果は未定義(undefined) となります。

### パラメータ

`num`

  もととなる数。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`exponent`

  正の数で、`num` を何乗するかを指定します。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`modulus`

  モジュロ。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

結果を GMP 数で返します。

### 例

例1 gmp_powm() の例

    <?php
    $pow1 = gmp_powm("2", "31", "2147483649");
    echo gmp_strval($pow1) . "\n";
    ?>

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

    2147483648

# gmp_prob_prime

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_prob_prime — 数が"おそらく素数"であるかどうかを調べる

### 説明

function gmp_prob_prime(GMP|int|string `$num`, int `$repetitions` = 10): int

この関数は、Miller-Rabin の確率的テストを使用して、 その数が素数かどうかを調べます。

### パラメータ

`num`

  素数かどうかを調べたい数。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`repetitions`

  `repetitions` の合理的な値は 5 から 10 くらいまで変動します (デフォルトは 10 です)。より大きい値を指定すると、素数でない数を 「おそらく素数である」と誤認識する可能性が小さくなります。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

この関数が 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_random

(PHP 4 >= 4.0.4, PHP 5, PHP 7)

gmp_random — 乱数を生成する

警告

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

### 説明

function 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 オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

ランダムな 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_bits

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

gmp_random_bits — 乱数を生成する

### 説明

function 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_range

(PHP 5 >= 5.6.3, PHP 7, PHP 8)

gmp_random_range — 等確率に選ばれた整数を取得する

### 説明

function 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_seed

(PHP 7, PHP 8)

gmp_random_seed — 乱数シードを設定する

### 説明

function gmp_random_seed(GMP|int|string `$seed`): void

### パラメータ

`seed`

  gmp_random(), gmp_random_bits(), gmp_random_range() 向けに設定するシード

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

値を返しません。

### エラー / 例外

`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() - 等確率に選ばれた整数を取得する

# gmp_root

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

gmp_root — n乗根の整数部を返す

### 説明

function gmp_root(GMP|int|string `$num`, int `$nth`): GMP

`num` の `nth` 乗根を計算し、 その整数部を返します。

### パラメータ

`num`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`nth`

  `num` の正のべき乗根

### 戻り値

結果の整数部をGMP数として返します。

# gmp_rootrem

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

gmp_rootrem — n乗根の整数部分と小数部分を返す

### 説明

function gmp_rootrem(GMP|int|string `$num`, int `$nth`): array

`num` の `nth` 乗根を計算し、 整数部分と小数部分を返します。

### パラメータ

`num`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`nth`

  `num` の正のn乗根

### 戻り値

ふたつの要素の配列を返します。 最初の要素はn乗根の整数部分、ふたつめの要素は小数部分です。 両方ともGMP数として表現されます。

# gmp_scan0

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_scan0 — 0 を探す

### 説明

function gmp_scan0(GMP|int|string `$num1`, int `$start`): int

ビット `start` から最上位ビットの方に、 最初のクリアビットが見付かるまで `num1` をスキャンします。

### パラメータ

`num1`

  スキャンする数。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`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

# gmp_scan1

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_scan1 — 1 を探す

### 説明

function gmp_scan1(GMP|int|string `$num1`, int `$start`): int

ビット `start` から最上位ビットの方に、 セットされているビットが最初に見付かるまで `num1` をスキャンします。

### パラメータ

`num1`

  スキャンする数。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`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_setbit

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_setbit — ビットを設定する

### 説明

function gmp_setbit(GMP `$num`, int `$index`, bool `$value` = `true`): void

`num` のビット `index` を設定します。

### パラメータ

`num`

  GMP オブジェクト

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`index`

  設定するビットのインデックス。0 は最下位ビットを表します。

`value`

  true にするとそのビットを設定し (値を 1/on にし)、 false にするとそのビットをクリアします (値を 0/off にします)。

### 戻り値

値を返しません。

### 例

例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_sign

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sign — 数の符号

### 説明

function 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_sqrt

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sqrt — 平方根を計算する

### 説明

function gmp_sqrt(GMP|int|string `$num`): GMP

`num` の平方根を計算します。

### パラメータ

`num`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

平方根の整数部分を 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_sqrtrem

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sqrtrem — 余りつきの平方根

### 説明

function gmp_sqrtrem(GMP|int|string `$num`): array

ある数の平方根を余りつきで計算します。

### パラメータ

`num`

  平方根を計算したい数。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

最初の要素が `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_strval

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_strval — GMP 数を文字列に変換する

### 説明

function gmp_strval(GMP|int|string `$num`, int `$base` = 10): string

GMP 数を `base` を基数とする文字列表現に変換します。 デフォルトの基数は 10 です。

### パラメータ

`num`

  文字列の変換したい GMP 数。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`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_sub

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_sub — 数値の減算

### 説明

function gmp_sub(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

`num1` から `num2` を引いた結果を返します。

### パラメータ

`num1`

  引かれる数。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`num2`

  `num1` から引く数。

  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

GMP オブジェクトを返します。

### 例

例1 gmp_sub() の例

    <?php
    $sub = gmp_sub("281474976710656", "4294967296"); // 2^48 - 2^32
    echo gmp_strval($sub) . "\n";
    ?>

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

    281470681743360

# gmp_testbit

(PHP 5 >= 5.3.0, PHP 7, PHP 8)

gmp_testbit — ビットが設定されているかどうかを調べる

### 説明

function gmp_testbit(GMP|int|string `$num`, int `$index`): bool

指定したビットが設定されているかどうかを調べます。

### パラメータ

`num`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`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() - ビットをクリアする

# gmp_xor

(PHP 4 >= 4.0.4, PHP 5, PHP 7, PHP 8)

gmp_xor — ビット XOR を計算する

### 説明

function gmp_xor(GMP|int|string `$num1`, GMP|int|string `$num2`): GMP

2 つの GMP 数のビット排他的論理和 (XOR) を計算します。

### パラメータ

`num1`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。
`num2`
  GMP オブジェクト、int、 あるいは数値として解釈可能な string。 文字列の場合、gmp_init() で基数を自動検出するとき (`base` に 0 を指定したとき) と同じ方法で解釈されます。

### 戻り値

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_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 クラス

(PHP 5 >= 5.6.0, PHP 7, PHP 8)

## はじめに

GMP 数。このオブジェクトは、オーバーロードされた 算術演算子, ビット演算子, 比較演算子 をサポートしています。

> 注意:

> GMP オブジェクトを操作するオブジェクト指向インターフェイスは用意されていません。 手続き型の GMP API を使いましょう。

## クラス概要

final class GMP {
/* メソッド */
public function __construct(int|string `$num` = 0, int `$base` = 0)
public function __serialize(): array
public function __unserialize(array `$data`): void
}

## 変更履歴

バージョン | 説明
--- | ---
8.4.0 | GMP は final として定義されました。

# GMP::__construct

(PHP 8 >= 8.2.4)

GMP::__construct — GMP数を作成する

### 説明

public function GMP::__construct(int|string `$num` = 0, int `$base` = 0)

整数または文字列から、GMP数を作成します。

### パラメータ

`num`
  整数値あるいは文字列。文字列表現には、 10進数か16進数か8進数、あるいは2進数を使用可能です。
`base`
  文字列表現を変換するのに使う基数 明示的に基数を指定する場合、 `2` から `62` までの値を指定できます。 `36` までの場合、大文字小文字は無視されます。 つまり、大文字だろうと小文字だろうと、同じ値だということです。 `37` から `62` までの場合、 大文字の値は `10` から `35` までの値を示し、小文字の値は `36` から `61` までの値を示します。 `base` を `0` にした場合、 実際の基数の解釈は `num` の先頭の文字によって決まります。 最初の2文字が `0x` や `0X` の場合、 文字列は16進数として解釈されます。 最初の2文字が `0b` や `0B` の場合、 文字列は2進数として解釈されます。 最初の2文字が `0o` や `0O` の場合、 文字列は8進数として解釈されます。 さらに、最初の文字が `0` の場合も、 文字列は8進数として解釈されます。 上記以外の場合は全て、文字列は10進数として解釈されます。

### 参考

- gmp_init() - GMP 数を作成する

# GMP::__serialize

(PHP 8 >= 8.1.0)

GMP::__serialize — GMP オブジェクトをシリアライズする

### 説明

public function GMP::__serialize(): array

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

値を返しません。

# GMP::__unserialize

(PHP 8 >= 8.1.0)

GMP::__unserialize — `data` 引数をGMP オブジェクトとして復元する

### 説明

public function GMP::__unserialize(array `$data`): void

警告

この関数は、 現在のところ詳細な情報はありません。引数のリストのみが 記述されています。

### パラメータ

`data`

  アンシリアライズされる値。

### 戻り値

値を返しません。

## 目次

- GMP::__construct — GMP数を作成する
- GMP::__serialize — GMP オブジェクトをシリアライズする
- GMP::__unserialize — data 引数をGMP オブジェクトとして復元する

- インストール/設定
  - 要件
  - インストール手順
- 定義済み定数
- 例
- 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 オブジェクトとして復元する

# 数学関数

# はじめに

これらの数学関数は、実行するコンピューターの int型および float型の範囲で のみ値を処理します。 より大きな数を処理する必要がある場合には、 任意精度数学関数 や GNU Multiple Precision(GMP) の使用をお勧めします。

## 参考

- 算術演算子
- 任意精度数学関数
- GNU Multiple Precision(GMP)

# 定義済み定数

以下の定数は、PHP コアに含まれており、常に利用可能です。

数学関連の定数
`M_PI` (float)
  π (pi) の近似値 (`3.14159265358979323846`).
`M_E` (float)
  Euler数 `e` の近似値 (`2.7182818284590452354`).
`M_LOG2E` (float)
  `log2(e)` の近似値 (`1.4426950408889634074`).
`M_LOG10E` (float)
  `log10(e)` の近似値 (`0.43429448190325182765`).
`M_LN2` (float)
  `ln(2)` の近似値 (`0.69314718055994530942`).
`M_LN10` (float)
  `ln(10)` の近似値 (`2.30258509299404568402`).
`M_PI_2` (float)
  `π/2` の近似値 (`1.57079632679489661923`).
`M_PI_4` (float)
  `π/4` の近似値 (`0.78539816339744830962`).
`M_1_PI` (float)
  `1/π` の近似値 (`0.31830988618379067154`).
`M_2_PI` (float)
  `2/π` の近似値 (`0.63661977236758134308`).
`M_SQRTPI` (float)
  `sqrt(π)` の近似値 (`1.77245385090551602729`).
`M_2_SQRTPI` (float)
  `2/sqrt(π)` の近似値 (`1.12837916709551257390`).
`M_SQRT2` (float)
  `sqrt(2)` の近似値 (`1.41421356237309504880`).
`M_SQRT3` (float)
  `sqrt(3)` の近似値 (`1.73205080756887729352`).
`M_SQRT1_2` (float)
  `1/sqrt(2)` の近似値 (`0.70710678118654752440`).
`M_LNPI` (float)
  `ln(π)` の近似値 (`1.14472988584940017414`).
`M_EULER` (float)
  Euler's constant γ の近似値 (`0.57721566490153286061`).

IEEE 754 浮動小数点数の定数
`NAN` (float)
  Not A Number
`INF` (float)
  Infinity

丸め定数

> 注意: PHP 8.4.0 以降は、 RoundingMode enum を代わりに使うことを推奨します。

`PHP_ROUND_HALF_UP` (int)
  ゼロから離れる方向に丸めます。
`PHP_ROUND_HALF_DOWN` (int)
  ゼロに近づく方向に丸めます。
`PHP_ROUND_HALF_EVEN` (int)
  もっとも近い偶数に丸めます。
`PHP_ROUND_HALF_ODD` (int)
  もっとも近い奇数に丸めます。

# RoundingMode Enum

(PHP 8 >= 8.4.0)

## はじめに

列挙型の RoundingMode は、round() 、bcround() 、 BcMath\Number::round() で丸めの方法を指定するために使用されます。

## 列挙型概要

enum RoundingMode
{
case HalfAwayFromZero ; // 最も近い整数に丸めます。小数部分が `5` の場合は、絶対値が大きい方の整数に丸めます。
case HalfTowardsZero ; // 最も近い整数に丸めます。小数部分が `5` の場合は、絶対値が小さい方の整数に丸めます。
case HalfEven ; // 最も近い整数に丸めます。小数部分が `5` の場合は、偶数に丸めます。
case HalfOdd ; // 最も近い整数に丸めます。小数部分が `5` の場合は、奇数に丸めます。
case TowardsZero ; // 絶対値がより小さい、もしくは等しい、最も近い整数に丸めます。
case AwayFromZero ; // 絶対値がより大きい、もしくは等しい、最も近い整数に丸めます。
case NegativeInfinity ; // より小さい、もしくは等しい、最大の整数に丸めます。
case PositiveInfinity ; // より大きい、もしくは等しい、最小の整数に丸めます。
}

# Math 関数

# abs

(PHP 4, PHP 5, PHP 7, PHP 8)

abs — 絶対値

### 説明

function 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() - 数の符号

# acos

(PHP 4, PHP 5, PHP 7, PHP 8)

acos — 逆余弦（アークコサイン）

### 説明

function acos(float `$num`): float

`num` のアークコサインをラジアンで返します。 acos() は cos() の逆関数です。 つまり、acos() の定義域にある `num` の全ての値に対して、`$num == cos(acos($num))` が成立します。

### パラメータ

`num`

  処理する角度。

### 戻り値

`num` のアークコサインをラジアンで返します。

### 参考

- cos() - 余弦（コサイン）
- acosh() - 逆双曲線余弦（アークハイパボリックコサイン）
- asin() - 逆正弦（アークサイン）
- atan() - 逆正接（アークタンジェント）

# acosh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

acosh — 逆双曲線余弦（アークハイパボリックコサイン）

### 説明

function acosh(float `$num`): float

`num` のアークハイパボリックコサインを返します。 つまり、ハイパボリックコサインが `num` となる値です。

### パラメータ

`num`

  処理する値。

### 戻り値

`num` のアークハイパボリックコサインを返します。

### 参考

- cosh() - 双曲線余弦（ハイパボリックコサイン）
- acos() - 逆余弦（アークコサイン）
- asinh() - 逆双曲線正弦（アークハイパボリックサイン）
- atanh() - 逆双曲線正接（アークハイパボリックタンジェント）

# asin

(PHP 4, PHP 5, PHP 7, PHP 8)

asin — 逆正弦（アークサイン）

### 説明

function asin(float `$num`): float

`num` のアークサインをラジアンで返します。 asin() は sin() の逆関数です。 つまり、asin() の定義域にある `num` の全ての値に対して、`$num == sin(asin($num))` が成立します。

### パラメータ

`num`

  処理する角度。

### 戻り値

`num` のアークサインをラジアンで返します。

### 参考

- sin() - 正弦（サイン）
- asinh() - 逆双曲線正弦（アークハイパボリックサイン）
- acos() - 逆余弦（アークコサイン）
- atan() - 逆正接（アークタンジェント）

# asinh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

asinh — 逆双曲線正弦（アークハイパボリックサイン）

### 説明

function asinh(float `$num`): float

`num` のアークハイパボリックサインを返します。 つまり、ハイパボリックサインが `num` となる値です。

### パラメータ

`num`

  処理する角度。

### 戻り値

`num` のアークハイパボリックサインを返します。

### 参考

- sinh() - 双曲線正弦（ハイパボリックサイン）
- asin() - 逆正弦（アークサイン）
- acosh() - 逆双曲線余弦（アークハイパボリックコサイン）
- atanh() - 逆双曲線正接（アークハイパボリックタンジェント）

# atan

(PHP 4, PHP 5, PHP 7, PHP 8)

atan — 逆正接（アークタンジェント）

### 説明

function atan(float `$num`): float

`num` のアークタンジェントをラジアンで返します。 atan() は tan() の逆関数です。 つまり、atan() の定義域にある `num` の全ての値に対して、`$num == tan(atan($num))` が成立します。

### パラメータ

`num`

  処理する引数。

### 戻り値

`num` のアークタンジェントをラジアンで返します。

### 参考

- tan() - 正接（タンジェント）
- atanh() - 逆双曲線正接（アークハイパボリックタンジェント）
- asin() - 逆正弦（アークサイン）
- acos() - 逆余弦（アークコサイン）

# atan2

(PHP 4, PHP 5, PHP 7, PHP 8)

atan2 — 2 変数のアークタンジェント

### 説明

function atan2(float `$y`, float `$x`): float

この関数は、2 つの変数 `x` および `y` のアークタンジェントを計算します。 `y` / `x` のアークタンジェントを計算するのに似ていますが、 2 つの引数の符号を用いて結果の象限を定義することが異なっています。

この関数は、結果を -PI から PI の間(両端を含む)のラジアンで返します。

### パラメータ

`y`

  被除数。

`x`

  除数。

### 戻り値

`y`/`x` のアークタンジェントをラジアンで返します。

### 参考

- atan() - 逆正接（アークタンジェント）

# atanh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

atanh — 逆双曲線正接（アークハイパボリックタンジェント）

### 説明

function atanh(float `$num`): float

`num` のアークハイパボリックタンジェントを返します。 つまり、ハイパボリックタンジェントが `num` となる値です。

### パラメータ

`num`

  処理する引数。

### 戻り値

`num` のアークハイパボリックタンジェントを返します。

### 参考

- tanh() - 双曲線正接（ハイパボリックタンジェント）
- atan() - 逆正接（アークタンジェント）
- asinh() - 逆双曲線正弦（アークハイパボリックサイン）
- acosh() - 逆双曲線余弦（アークハイパボリックコサイン）

# base_convert

(PHP 4, PHP 5, PHP 7, PHP 8)

base_convert — 数値の基数を任意に変換する

### 説明

function 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() - 変数の整数としての値を取得する

# bindec

(PHP 4, PHP 5, PHP 7, PHP 8)

bindec — 2 進数 を 10 進数に変換する

### 説明

function 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() - 数値の基数を任意に変換する

# ceil

(PHP 4, PHP 5, PHP 7, PHP 8)

ceil — 端数の切り上げ

### 説明

function ceil(int|float `$num`): float

必要に応じて `num` を切り上げ、 `num` の次に大きい整数値を返します。

### パラメータ

`num`

  丸める値。

### 戻り値

`num` の次に大きい整数値を返します。 ceil() の戻り値は float 型と なります。これは、float 値の範囲は通常 int よりも広いためです。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `num` は、 数値への変換をサポートした内部オブジェクトを受け入れなくなりました。

### 例

例1 ceil() の例

    <?php
    echo ceil(4.3), PHP_EOL;    // 5
    echo ceil(9.999), PHP_EOL;  // 10
    echo ceil(-3.14), PHP_EOL;  // -3
    ?>

### 参考

- floor() - 端数の切り捨て
- round() - 浮動小数点数を丸める

# cos

(PHP 4, PHP 5, PHP 7, PHP 8)

cos — 余弦（コサイン）

### 説明

function cos(float `$num`): float

cos() は、`num` のコサインを 返します。`num` はラジアンです。

### パラメータ

`num`

  ラジアンで表した角度。

### 戻り値

`num` のコサインを返します。

### 例

例1 cos() の例

    <?php

    echo cos(M_PI); // -1

    ?>

### 参考

- acos() - 逆余弦（アークコサイン）
- sin() - 正弦（サイン）
- tan() - 正接（タンジェント）
- deg2rad() - 度単位の数値をラジアン単位に変換する

# cosh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

cosh — 双曲線余弦（ハイパボリックコサイン）

### 説明

function cosh(float `$num`): float

`num` のハイパボリックコサインを返します。 これは、`(exp($num) + exp(-$num))/2` で定義されます。

### パラメータ

`num`

  処理する引数。

### 戻り値

`num` のハイパボリックコサインを返します。

### 参考

- cos() - 余弦（コサイン）
- acosh() - 逆双曲線余弦（アークハイパボリックコサイン）
- sinh() - 双曲線正弦（ハイパボリックサイン）
- tanh() - 双曲線正接（ハイパボリックタンジェント）

# decbin

(PHP 4, PHP 5, PHP 7, PHP 8)

decbin — 10 進数を 2 進数に変換する

### 説明

function 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`

# dechex

(PHP 4, PHP 5, PHP 7, PHP 8)

dechex — 10 進数を 16 進数に変換する

### 説明

function 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() - 数値の基数を任意に変換する

# decoct

(PHP 4, PHP 5, PHP 7, PHP 8)

decoct — 10 進数を 8 進数に変換する

### 説明

function 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() - 数値の基数を任意に変換する

# deg2rad

(PHP 4, PHP 5, PHP 7, PHP 8)

deg2rad — 度単位の数値をラジアン単位に変換する

### 説明

function deg2rad(float `$num`): float

この関数は、`num` の単位を度からラジアンに変換します。

### パラメータ

`num`

  度で表した角度。

### 戻り値

`num` と同等な値をラジアンで表したものを返します。

### 例

例1 deg2rad() の例

    <?php

    echo deg2rad(45), PHP_EOL; // 0.785398163397
    var_dump(deg2rad(45) === M_PI_4); // bool(true)

    ?>

### 参考

- rad2deg() - ラジアン単位の数値を度単位に変換する

# exp

(PHP 4, PHP 5, PHP 7, PHP 8)

exp — `e` の累乗を計算する

### 説明

function exp(float `$num`): float

`e` を `num` 乗した値を返します。

> 注意:

> '`e`' は自然対数の底で、およそ 2.718282 です。

### パラメータ

`num`

  処理する引数。

### 戻り値

'e' の `num` 乗を返します。

### 例

例1 exp() の例

    <?php
    echo exp(12), PHP_EOL;
    echo exp(5.7);
    ?>

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

    162754.791419
    298.86740096706

### 参考

- log() - 自然対数
- pow() - 指数表現

# expm1

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

expm1 — 値がゼロに近い時にでも精度を保つために exp(number) - 1 を返す

### 説明

function expm1(float `$num`): float

expm1() は、 `exp($`num`) - 1` の値を返します。 `num` がゼロに近く、 `exp($`num`) - 1` が引き算時の桁落ちのために 不正確となるような場合でも正確な値が計算できる方法を使用します。

### パラメータ

`num`

  処理する引数。

### 戻り値

`e` の `num` 乗から 1 を引いた値を返します。

### 参考

- log1p() - 値がゼロに近い時にでも精度を保つ方法で計算した log(1 + number) を返す
- exp() - e の累乗を計算する

# fdiv

(PHP 8)

fdiv — IEEE 754 に従い、数値の除算を行う

### 説明

function 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() - 引数で除算をした際の剰余を返す
- fpow() - IEEE 754 に従い、数値をべき乗する

# floor

(PHP 4, PHP 5, PHP 7, PHP 8)

floor — 端数の切り捨て

### 説明

function floor(int|float `$num`): float

必要に応じて `num` を丸めることにより、 `num` をこえない最大の整数の値を (float 型で) 返します。

### パラメータ

`num`

  丸める数値。

### 戻り値

`num` をこえない最大の整数の値を返します。 floor() の戻り値は float 型のままとなります。

### 変更履歴

バージョン | 説明
--- | ---
8.0.0 | `num` は、 数値への変換をサポートした内部オブジェクトを受け入れなくなりました。

### 例

例1 floor() の例

    <?php
    echo floor(4.3), PHP_EOL;   // 4
    echo floor(9.999), PHP_EOL; // 9
    echo floor(-3.14), PHP_EOL; // -4
    ?>

### 参考

- ceil() - 端数の切り上げ
- round() - 浮動小数点数を丸める

# fmod

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

fmod — 引数で除算をした際の剰余を返す

### 説明

function fmod(float `$num1`, float `$num2`): float

被除数（`num1`）を除数（`num2`） で割った余りを返します。余り（r）は、 整数 i を使用して num1 = i * num2 + r で定義されます。 `num2` がゼロ以外の場合はr は `num1` と同符号で、絶対値は `num2` より小さくなります。

### パラメータ

`num1`

  被除数。

`num2`

  除数。

### 戻り値

`num1`/`num2` の浮動小数点の剰余を返します。 第二引数が 0 の場合は `NAN` (float) を返します。

### 例

例1 fmod() の使用法

    <?php
    $x = 5.7;
    $y = 1.3;
    $r = fmod($x, $y);
    // $r は 0.5 です。なぜなら 4 * 1.3 + 0.5 = 5.7 だからです。

    var_dump($x, $y, $r);
    ?>

### 参考

- `/` - 浮動小数点数値の除算
- `%` - 整数値の剰余
- intdiv() - 整数値の除算 - 整数値の除算

# fpow

(PHP 8 >= 8.4.0)

fpow — IEEE 754 に従い、数値をべき乗する

### 説明

function fpow(float `$num`, float `$exponent`): float

`num` の `exponent` 乗の結果を浮動小数点数として返します。 `num` が 0 で `exponent` が負数の場合は、 `INF` を返します。

### パラメータ

`num`
  使用する基数。
`exponent`
  指数。

### 戻り値

`$num$exponent` を float で返します。

### 例

例1 fpow() の例

    <?php
    var_dump(fpow(10, 2));
    var_dump(fpow(0, -3));
    var_dump(fpow(-1, 5.5));
    ?>

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

    float(100)
    float(INF)
    float(NAN)

### 参考

- べき乗演算子 `**`
- pow() - 指数表現
- fdiv() - IEEE 754 に従い、数値の除算を行う
- fmod() - 引数で除算をした際の剰余を返す

# hexdec

(PHP 4, PHP 5, PHP 7, PHP 8)

hexdec — 16 進数を 10 進数に変換する

### 説明

function 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("ee")); // prints "int(238)"
    var_dump(hexdec("a0")); // prints "int(160)"
    ?>

例2 不正な文字を hexdec() に適用した例

    <?php
    var_dump(hexdec("See"));  // print "int(238)"
    var_dump(hexdec("that")); // print "int(10)"
    ?>

### 注意

> 注意:

> この関数は、プラットフォームの int 型に収まらない大きな数も変換できます。 その場合、結果は float で返します。

### 参考

- dechex() - 10 進数を 16 進数に変換する
- bindec() - 2 進数 を 10 進数に変換する
- octdec() - 8 進数を 10 進数に変換する
- base_convert() - 数値の基数を任意に変換する

# hypot

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

hypot — 直角三角形の斜辺の長さを計算する

### 説明

function hypot(float `$x`, float `$y`): float

hypot() は、直角をはさむ 2 辺の長さが `x` および `y` である 直角三角形の斜辺の長さ、すなわち原点と (`x`, `y`) との距離を返します。 これは `sqrt($x*$x + $y*$y)` と等価です。

### パラメータ

`x`

  最初の辺の長さ。

`y`

  二番目の辺の長さ。

### 戻り値

斜辺の長さを返します。

# intdiv

(PHP 7, PHP 8)

intdiv — 整数値の除算

### 説明

function 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));
    ?>

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

    int(1)
    int(-1)
    int(-1)
    int(1)
    int(1)
    int(1)

例2 intdiv() に不正な除数を使った例

    <?php
    try {
        intdiv(PHP_INT_MIN, -1);
    } catch (Error $e) {
        echo get_class($e), ': ', $e->getMessage(), PHP_EOL;
    }

    try
        intdiv(1, 0);
    } catch (Error $e) {
        echo get_class($e), ': ', $e->getMessage(), PHP_EOL;
    }
    ?>

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

    ArithmeticError: Division of PHP_INT_MIN by -1 is not an integer
    DivisionByZeroError: Division by zero

### 参考

- `/` - 浮動小数点数値の除算
- `%` - 整数値の剰余
- fmod() - 引数で除算をした際の剰余を返す - 浮動小数点数値の剰余

# is_finite

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_finite — 浮動小数点数の値が、有限の数値であるかどうかを調べる

### 説明

function 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_infinite

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_infinite — 浮動小数点数の値が、無限大であるかどうかを調べる

### 説明

function 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_nan

(PHP 4 >= 4.2.0, PHP 5, PHP 7, PHP 8)

is_nan — 浮動小数点数の値が、非数かどうかを調べる

### 説明

function 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() - 浮動小数点数の値が、無限大であるかどうかを調べる

# log

(PHP 4, PHP 5, PHP 7, PHP 8)

log — 自然対数

### 説明

function 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() - 定義されたエラー処理ルーチンにエラーメッセージを送信する

# log10

(PHP 4, PHP 5, PHP 7, PHP 8)

log10 — 底が 10 の対数

### 説明

function log10(float `$num`): float

底を 10 とする `num` の対数を返します。

### パラメータ

`num`

  処理する引数。

### 戻り値

底を 10 とする `num` の対数を返します。

### 参考

- log() - 自然対数

# log1p

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

log1p — 値がゼロに近い時にでも精度を保つ方法で計算した log(1 + number) を返す

### 説明

function log1p(float `$num`): float

log1p() は、 log(1 + `num`) の値を返します。 `num` がゼロに近い場合でも正確な値が 計算できる方法を使用します。 log() は、このような場合には 精度の問題で log(1) の値を返してしまいます。

### パラメータ

`num`

  処理する引数。

### 戻り値

log(1 + `num`) を返します。

### 参考

- expm1() - 値がゼロに近い時にでも精度を保つために exp(number) - 1 を返す
- log() - 自然対数
- log10() - 底が 10 の対数

# max

(PHP 4, PHP 5, PHP 7, PHP 8)

max — 最大値を返す

### 説明

function max(mixed `$value`, mixed `...$values`): mixed

代替のシグネチャ (名前付き引数をサポートしていません):

function 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), PHP_EOL;  // 7
    echo max(array(2, 4, 5)), PHP_EOL; // 5

    // -1 と 0 の比較なので、'hello' のほうが大きくなります
    echo max('hello', -1), PHP_EOL;    // hello

    // 長さが異なる複数の配列を渡すと、いちばん長い配列を返します
    $val = max(array(2, 2, 2), array(1, 1, 1, 1)); // array(1, 1, 1, 1)
    var_dump($val);

    // 同じ長さの複数の配列を渡すと、max はその要素を左から
    // 辞書順に比較します。この例では 2 == 2 ですが 5 > 4 となります
    $val = max(array(2, 4, 8), array(2, 5, 1)); // array(2, 5, 1)
    var_dump($val);

    // 配列と配列でない値が渡された場合、常に
    // 配列が最大と判定されます。
    $val = max('string', array(2, 5, 7), 42);   // array(2, 5, 7)
    var_dump($val);

    // 一方の値が NULL や boolean の場合、それを他の値と比較するときには、
    // もう一方の値の型が何であるかにかかわらず、FALSE < TRUE というルールを使います。
    // 以下の例では、-10 は TRUE と評価されます。
    $val = max(-10, FALSE); // -10
    var_dump($val);

    // 一方 0 は FALSE と評価されるので、TRUE よりは小さいとみなされます。
    $val = max(0, TRUE); // TRUE
    var_dump($val);
    ?>

### 参考

- min() - 最小値を返す
- count() - 配列または Countable オブジェクトに含まれるすべての要素の数を数える

# min

(PHP 4, PHP 5, PHP 7, PHP 8)

min — 最小値を返す

### 説明

function min(mixed `$value`, mixed `...$values`): mixed

代替のシグネチャ (名前付き引数をサポートしていません):

function 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), PHP_EOL;  // 1
    echo min(array(2, 4, 5)), PHP_EOL; // 2

    // -1 と 0 の比較なので、-1 のほうが小さくなります
    echo min('hello', -1), PHP_EOL;    // -1

    // 長さが異なる複数の配列を渡すと、いちばん短い配列を返します
    $val = min(array(2, 2, 2), array(1, 1, 1, 1)); // array(2, 2, 2)
    var_dump($val);

    // 同じ長さの複数の配列を渡すと、max はその要素を左から
    // 辞書順に比較します。この例では 2 == 2 ですが 4 < 5 となります
    $val = min(array(2, 4, 8), array(2, 5, 1)); // array(2, 4, 8)
    var_dump($val);

    // 配列と配列でない値が渡された場合、常に
    // 配列が最大と判定されます。
    $val = min('string', array(2, 5, 7), 42);   // string
    var_dump($val);

    // 一方の値が NULL や boolean の場合、それを他の値と比較するときには、
    // もう一方の値の型が何であるかにかかわらず、
    // FALSE < TRUE / NULL == FALSE というルールを使います。
    // 以下の例では、-10 と 10 はどちらも TRUE と評価されます。
    $val = min(-10, FALSE, 10); // FALSE
    var_dump($val);

    $val = min(-10, NULL, 10);  // NULL
    var_dump($val);

    // 一方 0 は FALSE と評価されるので、TRUE よりは小さいとみなされます。
    $val = min(0, TRUE); // 0
    var_dump($val);
    ?>

### 参考

- max() - 最大値を返す
- count() - 配列または Countable オブジェクトに含まれるすべての要素の数を数える

# octdec

(PHP 4, PHP 5, PHP 7, PHP 8)

octdec — 8 進数を 10 進数に変換する

### 説明

function 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() - 数値の基数を任意に変換する

# pi

(PHP 4, PHP 5, PHP 7, PHP 8)

pi — 円周率の値を得る

### 説明

function pi(): float

円周率の近似値を返します。 また、定数 `M_PI` を使用することで pi() とまったく同じ結果を取得することも可能です。

### パラメータ

この関数にはパラメータはありません。

### 戻り値

円周率の値を不動小数点数で返します。

### 例

例1 pi() の例

    <?php
    echo pi(), PHP_EOL; // 3.1415926535898
    echo M_PI, PHP_EOL; // 3.1415926535898
    ?>

# pow

(PHP 4, PHP 5, PHP 7, PHP 8)

pow — 指数表現

### 説明

function pow(mixed `$num`, mixed `$exponent`): int|float|object

`num` の `exponent` 乗を返します。

> 注意:

> ** 演算子も使えます。

### パラメータ

`num`

  使用する基数。

`exponent`

  指数。

### 戻り値

`num` の `exponent` 乗を返します。 両方の引数が非負の整数で、かつ結果が int 型の範囲に収まる場合は、結果を int 型で返します。 それ以外の場合は結果を float 型で返します。

PHP の拡張モジュールは、この演算の振る舞いを上書きし、オブジェクトを返させても構いません。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 基数が `0` の場合に、 `exponent` を負数とするのは非推奨となりました。

### 例

例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

    echo pow(-1, 5.5), PHP_EOL; // NAN
    ?>

例2 GMP オブジェクトと一緒に pow() を使う例

    <?php
    var_dump(pow(new GMP("3"), new GMP("2"))); // object(GMP)
    ?>

### 注意

> 注意:

> この関数はすべての入力を (スカラー値以外でも) 数値に変換します。 その結果、予想外の 結果を引き起こすことがあります。

### 参考

- べき乗演算子 `**`
- fpow() - IEEE 754 に従い、数値をべき乗する
- exp() - e の累乗を計算する
- sqrt() - 平方根
- bcpow() - 任意精度数値をべき乗する
- gmp_pow() - べき乗を計算する

# rad2deg

(PHP 4, PHP 5, PHP 7, PHP 8)

rad2deg — ラジアン単位の数値を度単位に変換する

### 説明

function rad2deg(float `$num`): float

この関数は、`num` の単位をラジアンから度に変換します。

### パラメータ

`num`

  ラジアン値。

### 戻り値

`num` と同等な値を度で表したものを返します。

### 例

例1 rad2deg() の例

    <?php

    echo rad2deg(M_PI_4); // 45

    ?>

### 参考

- deg2rad() - 度単位の数値をラジアン単位に変換する

# round

(PHP 4, PHP 5, PHP 7, PHP 8)

round — 浮動小数点数を丸める

### 説明

function round(int|float `$num`, int `$precision` = 0, int|RoundingMode `$mode` = `RoundingMode::HalfAwayFromZero`): float

`num` を、指定した `precision`(小数点以下の桁数)に丸めた値を 返します。`precision` を負またはゼロ(デフォルト) とすることも可能です。

### パラメータ

`num`

  丸める値。

`precision`

  オプションで指定する、丸める桁数。

  `precision` が正の値の場合、 `num` は 小数点以下、有効桁数 `precision` 桁に丸められます。

  `precision` が負の場合、 `num` の 丸め処理は小数点より前の `precision` 桁に対して行われます。 つまり、一番近い `pow(10, -$precision)` の倍数に丸められます。 たとえば、`precision` が -1 の場合、 `num` は 一番近い10の倍数に、 `precision` が -2 の場合は 一番近い100の倍数に丸められる、という具合です。

`mode`

  RoundingMode もしくは次の定数のいずれかを使って、丸めのモードを指定します。

  定数 | 説明
  --- | ---
  `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 になります。

  ただし、新規に追加されたいくつかのモードは RoundingMode にのみ存在します。

### 戻り値

`precision` で与えられた精度に丸められた値を float で返します。

### エラー / 例外

この関数は、無効な `mode` が指定された場合に ValueError をスローします。 PHP 8.4.0 より前では、エラーにはならずに `PHP_ROUND_HALF_UP` を使用していました。

### 変更履歴

バージョン | 説明
--- | ---
8.4.0 | 新しい4つのモードが追加されました。
8.4.0 | 無効な `mode` が指定された場合に ValueError をスローするようになりました。
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)

例5 RoundingMode を使用した例

    <?php
    foreach (RoundingMode::cases() as $mode) {
        foreach ([
            8.5,
            9.5,
            -3.5,
        ] as $number) {
            printf("%-17s: %+.17g -> %+.17g\n", $mode->name, $number, round($number, 0, $mode));
        }
        echo "\n";
    }
    ?>

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

    HalfAwayFromZero : +8.5 -> +9
    HalfAwayFromZero : +9.5 -> +10
    HalfAwayFromZero : -3.5 -> -4

    HalfTowardsZero  : +8.5 -> +8
    HalfTowardsZero  : +9.5 -> +9
    HalfTowardsZero  : -3.5 -> -3

    HalfEven         : +8.5 -> +8
    HalfEven         : +9.5 -> +10
    HalfEven         : -3.5 -> -4

    HalfOdd          : +8.5 -> +9
    HalfOdd          : +9.5 -> +9
    HalfOdd          : -3.5 -> -3

    TowardsZero      : +8.5 -> +8
    TowardsZero      : +9.5 -> +9
    TowardsZero      : -3.5 -> -3

    AwayFromZero     : +8.5 -> +9
    AwayFromZero     : +9.5 -> +10
    AwayFromZero     : -3.5 -> -4

    NegativeInfinity : +8.5 -> +8
    NegativeInfinity : +9.5 -> +9
    NegativeInfinity : -3.5 -> -4

    PositiveInfinity : +8.5 -> +9
    PositiveInfinity : +9.5 -> +10
    PositiveInfinity : -3.5 -> -3

### 参考

- ceil() - 端数の切り上げ
- floor() - 端数の切り捨て
- number_format() - 数字を千の位毎にグループ化してフォーマットする

# sin

(PHP 4, PHP 5, PHP 7, PHP 8)

sin — 正弦（サイン）

### 説明

function sin(float `$num`): float

sin() は、`num` のサインを 返します。`num` はラジアンです。

### パラメータ

`num`

  ラジアンで表した値。

### 戻り値

`num` のサインを返します。

### 例

例1 sin() の例

    <?php

    // 結果の精度は、指定によります。
    echo sin(deg2rad(60)), PHP_EOL;  //  0.866025403 ...
    echo sin(60), PHP_EOL;           // -0.304810621 ...

    ?>

### 参考

- asin() - 逆正弦（アークサイン）
- sinh() - 双曲線正弦（ハイパボリックサイン）
- cos() - 余弦（コサイン）
- tan() - 正接（タンジェント）
- deg2rad() - 度単位の数値をラジアン単位に変換する

# sinh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

sinh — 双曲線正弦（ハイパボリックサイン）

### 説明

function sinh(float `$num`): float

`num` のハイパボリックサインを返します。 これは、`(exp($num) - exp(-$num))/2` で定義されます。

### パラメータ

`num`

  処理する引数。

### 戻り値

`num` のハイパボリックサインを返します。

### 参考

- sin() - 正弦（サイン）
- asinh() - 逆双曲線正弦（アークハイパボリックサイン）
- cosh() - 双曲線余弦（ハイパボリックコサイン）
- tanh() - 双曲線正接（ハイパボリックタンジェント）

# sqrt

(PHP 4, PHP 5, PHP 7, PHP 8)

sqrt — 平方根

### 説明

function sqrt(float `$num`): float

`num` の平方根を返します。

### パラメータ

`num`

  処理する引数。

### 戻り値

`num` の平方根を返します。 負の数を指定した場合は、特別な値 `NAN` を返します。

### 例

例1 sqrt() の例

    <?php
    // 小数点以下の精度は、precision ディレクティブの設定に依存します
    echo sqrt(9), PHP_EOL; // 3
    echo sqrt(10), PHP_EOL; // 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)`

# tan

(PHP 4, PHP 5, PHP 7, PHP 8)

tan — 正接（タンジェント）

### 説明

function 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() - 度単位の数値をラジアン単位に変換する

# tanh

(PHP 4 >= 4.1.0, PHP 5, PHP 7, PHP 8)

tanh — 双曲線正接（ハイパボリックタンジェント）

### 説明

function tanh(float `$num`): float

`num` のハイパボリックタンジェントを返します。 これは `sinh($num)/cosh($num)` で定義されます。

### パラメータ

`num`

  処理する引数。

### 戻り値

`num` のハイパボリックタンジェントを返します。

### 参考

- tan() - 正接（タンジェント）
- atanh() - 逆双曲線正接（アークハイパボリックタンジェント）
- sinh() - 双曲線正弦（ハイパボリックサイン）
- cosh() - 双曲線余弦（ハイパボリックコサイン）

## 目次

- 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 — 引数で除算をした際の剰余を返す
- fpow — IEEE 754 に従い、数値をべき乗する
- 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 — 双曲線正接（ハイパボリックタンジェント）

- 定義済み定数
- RoundingMode — RoundingMode Enum
- 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 — 引数で除算をした際の剰余を返す
  - fpow — IEEE 754 に従い、数値をべき乗する
  - 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 — 双曲線正接（ハイパボリックタンジェント）

# Statistics

# はじめに

警告

この拡張モジュールは、メンテナンスされていません。

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.

# インストール/設定

## 目次

- 要件
- インストール手順

## 要件

No external libraries are needed. The extension comes bundled with the libraries used.

## インストール手順

この » PECL 拡張モジュールは PHP にバンドルされていません。

この拡張モジュールは、メンテナンスされておらず開発が止まっています。 しかし、ソースコードは PECL SVN から取得できます。 » https://pecl.php.net/package/stats.

この PECL 拡張モジュールの Windows バイナリ (DLL ファイル) は、PECL のウェブサイトから取得できます。

# Statistic 関数

# stats_absolute_deviation

(PECL stats >= 1.0.0)

stats_absolute_deviation — Returns the absolute deviation of an array of values

### 説明

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

# stats_cdf_beta

(PECL stats >= 1.0.0)

stats_cdf_beta — Calculates any one parameter of the beta distribution given values for the others

### 説明

function 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`.

# stats_cdf_binomial

(PECL stats >= 1.0.0)

stats_cdf_binomial — Calculates any one parameter of the binomial distribution given values for the others

### 説明

function 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`.

# stats_cdf_cauchy

(PECL stats >= 1.0.0)

stats_cdf_cauchy — Calculates any one parameter of the Cauchy distribution given values for the others

### 説明

function 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`.

# 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

### 説明

function 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`.

# stats_cdf_exponential

(PECL stats >= 1.0.0)

stats_cdf_exponential — Calculates any one parameter of the exponential distribution given values for the others

### 説明

function 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`.

# stats_cdf_f

(PECL stats >= 1.0.0)

stats_cdf_f — Calculates any one parameter of the F distribution given values for the others

### 説明

function 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`.

# stats_cdf_gamma

(PECL stats >= 1.0.0)

stats_cdf_gamma — Calculates any one parameter of the gamma distribution given values for the others

### 説明

function 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`.

# stats_cdf_laplace

(PECL stats >= 1.0.0)

stats_cdf_laplace — Calculates any one parameter of the Laplace distribution given values for the others

### 説明

function 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`.

# stats_cdf_logistic

(PECL stats >= 1.0.0)

stats_cdf_logistic — Calculates any one parameter of the logistic distribution given values for the others

### 説明

function 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`.

# 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

### 説明

function 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`.

# 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

### 説明

function 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`.

# 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

### 説明

function 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`.

# 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

### 説明

function 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`.

# stats_cdf_normal

(PECL stats >= 1.0.0)

stats_cdf_normal — Calculates any one parameter of the normal distribution given values for the others

### 説明

function 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`.

# stats_cdf_poisson

(PECL stats >= 1.0.0)

stats_cdf_poisson — Calculates any one parameter of the Poisson distribution given values for the others

### 説明

function 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`.

# stats_cdf_t

(PECL stats >= 1.0.0)

stats_cdf_t — Calculates any one parameter of the t-distribution given values for the others

### 説明

function 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`.

# stats_cdf_uniform

(PECL stats >= 1.0.0)

stats_cdf_uniform — Calculates any one parameter of the uniform distribution given values for the others

### 説明

function 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`.

# stats_cdf_weibull

(PECL stats >= 1.0.0)

stats_cdf_weibull — Calculates any one parameter of the Weibull distribution given values for the others

### 説明

function 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`.

# stats_covariance

(PECL stats >= 1.0.0)

stats_covariance — Computes the covariance of two data sets

### 説明

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

# stats_dens_beta

(PECL stats >= 1.0.0)

stats_dens_beta — Probability density function of the beta distribution

### 説明

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

# stats_dens_cauchy

(PECL stats >= 1.0.0)

stats_dens_cauchy — Probability density function of the Cauchy distribution

### 説明

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

# stats_dens_chisquare

(PECL stats >= 1.0.0)

stats_dens_chisquare — Probability density function of the chi-square distribution

### 説明

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

# stats_dens_exponential

(PECL stats >= 1.0.0)

stats_dens_exponential — Probability density function of the exponential distribution

### 説明

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

# stats_dens_f

(PECL stats >= 1.0.0)

stats_dens_f — Probability density function of the F distribution

### 説明

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

# stats_dens_gamma

(PECL stats >= 1.0.0)

stats_dens_gamma — Probability density function of the gamma distribution

### 説明

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

# stats_dens_laplace

(PECL stats >= 1.0.0)

stats_dens_laplace — Probability density function of the Laplace distribution

### 説明

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

# stats_dens_logistic

(PECL stats >= 1.0.0)

stats_dens_logistic — Probability density function of the logistic distribution

### 説明

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

# stats_dens_normal

(PECL stats >= 1.0.0)

stats_dens_normal — Probability density function of the normal distribution

### 説明

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

# stats_dens_pmf_binomial

(PECL stats >= 1.0.0)

stats_dens_pmf_binomial — Probability mass function of the binomial distribution

### 説明

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

# stats_dens_pmf_hypergeometric

(PECL stats >= 1.0.0)

stats_dens_pmf_hypergeometric — Probability mass function of the hypergeometric distribution

### 説明

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

# stats_dens_pmf_negative_binomial

(PECL stats >= 1.0.0)

stats_dens_pmf_negative_binomial — Probability mass function of the negative binomial distribution

### 説明

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

# stats_dens_pmf_poisson

(PECL stats >= 1.0.0)

stats_dens_pmf_poisson — Probability mass function of the Poisson distribution

### 説明

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

# stats_dens_t

(PECL stats >= 1.0.0)

stats_dens_t — Probability density function of the t-distribution

### 説明

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

# stats_dens_uniform

(PECL stats >= 1.0.0)

stats_dens_uniform — Probability density function of the uniform distribution

### 説明

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

# stats_dens_weibull

(PECL stats >= 1.0.0)

stats_dens_weibull — Probability density function of the Weibull distribution

### 説明

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

# stats_harmonic_mean

(PECL stats >= 1.0.0)

stats_harmonic_mean — Returns the harmonic mean of an array of values

### 説明

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

# stats_kurtosis

(PECL stats >= 1.0.0)

stats_kurtosis — Computes the kurtosis of the data in the array

### 説明

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

# stats_rand_gen_beta

(PECL stats >= 1.0.0)

stats_rand_gen_beta — Generates a random deviate from the beta distribution

### 説明

function 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

# stats_rand_gen_chisquare

(PECL stats >= 1.0.0)

stats_rand_gen_chisquare — Generates a random deviate from the chi-square distribution

### 説明

function 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

# stats_rand_gen_exponential

(PECL stats >= 1.0.0)

stats_rand_gen_exponential — Generates a random deviate from the exponential distribution

### 説明

function 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

# stats_rand_gen_f

(PECL stats >= 1.0.0)

stats_rand_gen_f — Generates a random deviate from the F distribution

### 説明

function 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

# stats_rand_gen_funiform

(PECL stats >= 1.0.0)

stats_rand_gen_funiform — Generates uniform float between low (exclusive) and high (exclusive)

### 説明

function 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 (exclusive)

`high`

  The upper bound (exclusive)

### 戻り値

A random deviate

# stats_rand_gen_gamma

(PECL stats >= 1.0.0)

stats_rand_gen_gamma — Generates a random deviate from the gamma distribution

### 説明

function 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

# stats_rand_gen_ibinomial

(PECL stats >= 1.0.0)

stats_rand_gen_ibinomial — Generates a random deviate from the binomial distribution

### 説明

function 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

# stats_rand_gen_ibinomial_negative

(PECL stats >= 1.0.0)

stats_rand_gen_ibinomial_negative — Generates a random deviate from the negative binomial distribution

### 説明

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

# stats_rand_gen_int

(PECL stats >= 1.0.0)

stats_rand_gen_int — Generates random integer between 1 and 2147483562

### 説明

function stats_rand_gen_int(): int

Returns a random integer between 1 and 2147483562

### パラメータ

この関数にはパラメータはありません。

### 戻り値

A random integer

# stats_rand_gen_ipoisson

(PECL stats >= 1.0.0)

stats_rand_gen_ipoisson — Generates a single random deviate from a Poisson distribution

### 説明

function 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

# stats_rand_gen_iuniform

(PECL stats >= 1.0.0)

stats_rand_gen_iuniform — Generates integer uniformly distributed between LOW (inclusive) and HIGH (inclusive)

### 説明

function 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

# 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

### 説明

function 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

# stats_rand_gen_noncentral_f

(PECL stats >= 1.0.0)

stats_rand_gen_noncentral_f — Generates a random deviate from the noncentral F distribution

### 説明

function 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

# 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

### 説明

function 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

# stats_rand_gen_normal

(PECL stats >= 1.0.0)

stats_rand_gen_normal — Generates a single random deviate from a normal distribution

### 説明

function 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

# stats_rand_gen_t

(PECL stats >= 1.0.0)

stats_rand_gen_t — Generates a single random deviate from a t-distribution

### 説明

function 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

# stats_rand_get_seeds

(PECL stats >= 1.0.0)

stats_rand_get_seeds — Get the seed values of the random number generator

### 説明

function stats_rand_get_seeds(): array

Returns the current seed values of the random number generator

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns an array of two integers.

# stats_rand_phrase_to_seeds

(PECL stats >= 1.0.0)

stats_rand_phrase_to_seeds — Generate two seeds for the RGN random number generator

### 説明

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

# stats_rand_ranf

(PECL stats >= 1.0.0)

stats_rand_ranf — Generates a random floating point number between 0 and 1

### 説明

function 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

# stats_rand_setall

(PECL stats >= 1.0.0)

stats_rand_setall — Set seed values to the random generator

### 説明

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

# stats_skew

(PECL stats >= 1.0.0)

stats_skew — Computes the skewness of the data in the array

### 説明

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

# stats_standard_deviation

(PECL stats >= 1.0.0)

stats_standard_deviation — Returns the standard deviation

### 説明

function 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`.

# stats_stat_binomial_coef

(PECL stats >= 1.0.0)

stats_stat_binomial_coef — Returns a binomial coefficient

### 説明

function 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

# stats_stat_correlation

(PECL stats >= 1.0.0)

stats_stat_correlation — Returns the Pearson correlation coefficient of two data sets

### 説明

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

# stats_stat_factorial

(PECL stats >= 1.0.0)

stats_stat_factorial — Returns the factorial of an integer

### 説明

function stats_stat_factorial(int `$n`): float

Returns the factorial of an integer, `n`.

### パラメータ

`n`

  An integer

### 戻り値

The factorial of `n`.

# stats_stat_independent_t

(PECL stats >= 1.0.0)

stats_stat_independent_t — Returns the t-value from the independent two-sample t-test

### 説明

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

# stats_stat_innerproduct

(PECL stats >= 1.0.0)

stats_stat_innerproduct — Returns the inner product of two vectors

### 説明

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

# 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

### 説明

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

# stats_stat_percentile

(PECL stats >= 1.0.0)

stats_stat_percentile — Returns the percentile value

### 説明

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

# stats_stat_powersum

(PECL stats >= 1.0.0)

stats_stat_powersum — Returns the power sum of a vector

### 説明

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

# stats_variance

(PECL stats >= 1.0.0)

stats_variance — Returns the variance

### 説明

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

## 目次

- 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

- インストール/設定
  - 要件
  - インストール手順
- 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

# Technical Analysis for Traders

# はじめに

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 » https://ta-lib.org/.

# インストール/設定

## 目次

- 要件
- インストール手順
- 実行時設定

## 要件

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.

## 実行時設定

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

(PECL trader >= 0.2.0)

trader_acos — Vector Trigonometric ACos

### 説明

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

# trader_ad

(PECL trader >= 0.2.0)

trader_ad — Chaikin A/D Line

### 説明

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

# trader_add

(PECL trader >= 0.2.0)

trader_add — Vector Arithmetic Add

### 説明

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

# trader_adosc

(PECL trader >= 0.2.0)

trader_adosc — Chaikin A/D Oscillator

### 説明

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

# trader_adx

(PECL trader >= 0.2.0)

trader_adx — Average Directional Movement Index

### 説明

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

# trader_adxr

(PECL trader >= 0.2.0)

trader_adxr — Average Directional Movement Index Rating

### 説明

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

# trader_apo

(PECL trader >= 0.2.0)

trader_apo — Absolute Price Oscillator

### 説明

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

# trader_aroon

(PECL trader >= 0.2.0)

trader_aroon — Aroon

### 説明

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

# trader_aroonosc

(PECL trader >= 0.2.0)

trader_aroonosc — Aroon Oscillator

### 説明

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

# trader_asin

(PECL trader >= 0.2.0)

trader_asin — Vector Trigonometric ASin

### 説明

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

# trader_atan

(PECL trader >= 0.2.0)

trader_atan — Vector Trigonometric ATan

### 説明

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

# trader_atr

(PECL trader >= 0.2.0)

trader_atr — Average True Range

### 説明

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

# trader_avgprice

(PECL trader >= 0.2.0)

trader_avgprice — Average Price

### 説明

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

# trader_bbands

(PECL trader >= 0.2.0)

trader_bbands — Bollinger Bands

### 説明

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

# trader_beta

(PECL trader >= 0.2.0)

trader_beta — Beta

### 説明

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

# trader_bop

(PECL trader >= 0.2.0)

trader_bop — Balance Of Power

### 説明

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

# trader_cci

(PECL trader >= 0.2.0)

trader_cci — Commodity Channel Index

### 説明

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

# trader_cdl2crows

(PECL trader >= 0.2.0)

trader_cdl2crows — Two Crows

### 説明

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

# trader_cdl3blackcrows

(PECL trader >= 0.2.0)

trader_cdl3blackcrows — Three Black Crows

### 説明

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

# trader_cdl3inside

(PECL trader >= 0.2.0)

trader_cdl3inside — Three Inside Up/Down

### 説明

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

# trader_cdl3linestrike

(PECL trader >= 0.2.0)

trader_cdl3linestrike — Three-Line Strike

### 説明

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

# trader_cdl3outside

(PECL trader >= 0.2.0)

trader_cdl3outside — Three Outside Up/Down

### 説明

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

# trader_cdl3starsinsouth

(PECL trader >= 0.2.0)

trader_cdl3starsinsouth — Three Stars In The South

### 説明

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

# trader_cdl3whitesoldiers

(PECL trader >= 0.2.0)

trader_cdl3whitesoldiers — Three Advancing White Soldiers

### 説明

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

# trader_cdlabandonedbaby

(PECL trader >= 0.2.0)

trader_cdlabandonedbaby — Abandoned Baby

### 説明

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

# trader_cdladvanceblock

(PECL trader >= 0.2.0)

trader_cdladvanceblock — Advance Block

### 説明

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

# trader_cdlbelthold

(PECL trader >= 0.2.0)

trader_cdlbelthold — Belt-hold

### 説明

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

# trader_cdlbreakaway

(PECL trader >= 0.2.0)

trader_cdlbreakaway — Breakaway

### 説明

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

# trader_cdlclosingmarubozu

(PECL trader >= 0.2.0)

trader_cdlclosingmarubozu — Closing Marubozu

### 説明

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

# trader_cdlconcealbabyswall

(PECL trader >= 0.2.0)

trader_cdlconcealbabyswall — Concealing Baby Swallow

### 説明

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

# trader_cdlcounterattack

(PECL trader >= 0.2.0)

trader_cdlcounterattack — Counterattack

### 説明

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

# trader_cdldarkcloudcover

(PECL trader >= 0.2.0)

trader_cdldarkcloudcover — Dark Cloud Cover

### 説明

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

# trader_cdldoji

(PECL trader >= 0.2.0)

trader_cdldoji — Doji

### 説明

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

# trader_cdldojistar

(PECL trader >= 0.2.0)

trader_cdldojistar — Doji Star

### 説明

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

# trader_cdldragonflydoji

(PECL trader >= 0.2.0)

trader_cdldragonflydoji — Dragonfly Doji

### 説明

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

# trader_cdlengulfing

(PECL trader >= 0.2.0)

trader_cdlengulfing — Engulfing Pattern

### 説明

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

# trader_cdleveningdojistar

(PECL trader >= 0.2.0)

trader_cdleveningdojistar — Evening Doji Star

### 説明

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

# trader_cdleveningstar

(PECL trader >= 0.2.0)

trader_cdleveningstar — Evening Star

### 説明

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

# trader_cdlgapsidesidewhite

(PECL trader >= 0.2.0)

trader_cdlgapsidesidewhite — Up/Down-gap side-by-side white lines

### 説明

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

# trader_cdlgravestonedoji

(PECL trader >= 0.2.0)

trader_cdlgravestonedoji — Gravestone Doji

### 説明

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

# trader_cdlhammer

(PECL trader >= 0.2.0)

trader_cdlhammer — Hammer

### 説明

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

# trader_cdlhangingman

(PECL trader >= 0.2.0)

trader_cdlhangingman — Hanging Man

### 説明

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

# trader_cdlharami

(PECL trader >= 0.2.0)

trader_cdlharami — Harami Pattern

### 説明

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

# trader_cdlharamicross

(PECL trader >= 0.2.0)

trader_cdlharamicross — Harami Cross Pattern

### 説明

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

# trader_cdlhighwave

(PECL trader >= 0.2.0)

trader_cdlhighwave — High-Wave Candle

### 説明

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

# trader_cdlhikkake

(PECL trader >= 0.2.0)

trader_cdlhikkake — Hikkake Pattern

### 説明

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

# trader_cdlhikkakemod

(PECL trader >= 0.2.0)

trader_cdlhikkakemod — Modified Hikkake Pattern

### 説明

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

# trader_cdlhomingpigeon

(PECL trader >= 0.2.0)

trader_cdlhomingpigeon — Homing Pigeon

### 説明

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

# trader_cdlidentical3crows

(PECL trader >= 0.2.0)

trader_cdlidentical3crows — Identical Three Crows

### 説明

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

# trader_cdlinneck

(PECL trader >= 0.2.0)

trader_cdlinneck — In-Neck Pattern

### 説明

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

# trader_cdlinvertedhammer

(PECL trader >= 0.2.0)

trader_cdlinvertedhammer — Inverted Hammer

### 説明

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

# trader_cdlkicking

(PECL trader >= 0.2.0)

trader_cdlkicking — Kicking

### 説明

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

# trader_cdlkickingbylength

(PECL trader >= 0.2.0)

trader_cdlkickingbylength — Kicking - bull/bear determined by the longer marubozu

### 説明

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

# trader_cdlladderbottom

(PECL trader >= 0.2.0)

trader_cdlladderbottom — Ladder Bottom

### 説明

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

# trader_cdllongleggeddoji

(PECL trader >= 0.2.0)

trader_cdllongleggeddoji — Long Legged Doji

### 説明

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

# trader_cdllongline

(PECL trader >= 0.2.0)

trader_cdllongline — Long Line Candle

### 説明

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

# trader_cdlmarubozu

(PECL trader >= 0.2.0)

trader_cdlmarubozu — Marubozu

### 説明

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

# trader_cdlmatchinglow

(PECL trader >= 0.2.0)

trader_cdlmatchinglow — Matching Low

### 説明

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

# trader_cdlmathold

(PECL trader >= 0.2.0)

trader_cdlmathold — Mat Hold

### 説明

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

# trader_cdlmorningdojistar

(PECL trader >= 0.2.0)

trader_cdlmorningdojistar — Morning Doji Star

### 説明

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

# trader_cdlmorningstar

(PECL trader >= 0.2.0)

trader_cdlmorningstar — Morning Star

### 説明

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

# trader_cdlonneck

(PECL trader >= 0.2.0)

trader_cdlonneck — On-Neck Pattern

### 説明

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

# trader_cdlpiercing

(PECL trader >= 0.2.0)

trader_cdlpiercing — Piercing Pattern

### 説明

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

# trader_cdlrickshawman

(PECL trader >= 0.2.0)

trader_cdlrickshawman — Rickshaw Man

### 説明

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

# trader_cdlrisefall3methods

(PECL trader >= 0.2.0)

trader_cdlrisefall3methods — Rising/Falling Three Methods

### 説明

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

# trader_cdlseparatinglines

(PECL trader >= 0.2.0)

trader_cdlseparatinglines — Separating Lines

### 説明

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

# trader_cdlshootingstar

(PECL trader >= 0.2.0)

trader_cdlshootingstar — Shooting Star

### 説明

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

# trader_cdlshortline

(PECL trader >= 0.2.0)

trader_cdlshortline — Short Line Candle

### 説明

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

# trader_cdlspinningtop

(PECL trader >= 0.2.0)

trader_cdlspinningtop — Spinning Top

### 説明

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

# trader_cdlstalledpattern

(PECL trader >= 0.2.0)

trader_cdlstalledpattern — Stalled Pattern

### 説明

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

# trader_cdlsticksandwich

(PECL trader >= 0.2.0)

trader_cdlsticksandwich — Stick Sandwich

### 説明

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

# trader_cdltakuri

(PECL trader >= 0.2.0)

trader_cdltakuri — Takuri (Dragonfly Doji with very long lower shadow)

### 説明

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

# trader_cdltasukigap

(PECL trader >= 0.2.0)

trader_cdltasukigap — Tasuki Gap

### 説明

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

# trader_cdlthrusting

(PECL trader >= 0.2.0)

trader_cdlthrusting — Thrusting Pattern

### 説明

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

# trader_cdltristar

(PECL trader >= 0.2.0)

trader_cdltristar — Tristar Pattern

### 説明

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

# trader_cdlunique3river

(PECL trader >= 0.2.0)

trader_cdlunique3river — Unique 3 River

### 説明

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

# trader_cdlupsidegap2crows

(PECL trader >= 0.2.0)

trader_cdlupsidegap2crows — Upside Gap Two Crows

### 説明

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

# trader_cdlxsidegap3methods

(PECL trader >= 0.2.0)

trader_cdlxsidegap3methods — Upside/Downside Gap Three Methods

### 説明

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

# trader_ceil

(PECL trader >= 0.2.0)

trader_ceil — Vector Ceil

### 説明

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

# trader_cmo

(PECL trader >= 0.2.0)

trader_cmo — Chande Momentum Oscillator

### 説明

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

# trader_correl

(PECL trader >= 0.2.0)

trader_correl — Pearson's Correlation Coefficient (r)

### 説明

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

# trader_cos

(PECL trader >= 0.2.0)

trader_cos — Vector Trigonometric Cos

### 説明

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

# trader_cosh

(PECL trader >= 0.2.0)

trader_cosh — Vector Trigonometric Cosh

### 説明

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

# trader_dema

(PECL trader >= 0.2.0)

trader_dema — Double Exponential Moving Average

### 説明

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

# trader_div

(PECL trader >= 0.2.0)

trader_div — Vector Arithmetic Div

### 説明

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

# trader_dx

(PECL trader >= 0.2.0)

trader_dx — Directional Movement Index

### 説明

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

# trader_ema

(PECL trader >= 0.2.0)

trader_ema — Exponential Moving Average

### 説明

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

# trader_errno

(PECL trader >= 0.3.0)

trader_errno — Get error code

### 説明

function trader_errno(): int

Get error code of the last operation.

### パラメータ

この関数にはパラメータはありません。

### 戻り値

Returns the error code identified by one of the TRADER_ERR_* constants.

# trader_exp

(PECL trader >= 0.2.0)

trader_exp — Vector Arithmetic Exp

### 説明

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

# trader_floor

(PECL trader >= 0.2.0)

trader_floor — Vector Floor

### 説明

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

# trader_get_compat

(PECL trader >= 0.2.2)

trader_get_compat — Get compatibility mode

### 説明

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

# trader_get_unstable_period

(PECL trader >= 0.2.2)

trader_get_unstable_period — Get unstable period

### 説明

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

# trader_ht_dcperiod

(PECL trader >= 0.2.0)

trader_ht_dcperiod — Hilbert Transform - Dominant Cycle Period

### 説明

function trader_ht_dcperiod(array `$real`): array

### パラメータ

`real`

  実数値の配列。

### 戻り値

Returns an array with calculated data or false on failure.

# trader_ht_dcphase

(PECL trader >= 0.2.0)

trader_ht_dcphase — Hilbert Transform - Dominant Cycle Phase

### 説明

function trader_ht_dcphase(array `$real`): array

### パラメータ

`real`

  実数値の配列。

### 戻り値

Returns an array with calculated data or false on failure.

# trader_ht_phasor

(PECL trader >= 0.2.0)

trader_ht_phasor — Hilbert Transform - Phasor Components

### 説明

function trader_ht_phasor(array `$real`): array

### パラメータ

`real`

  実数値の配列。

### 戻り値

Returns an array with calculated data or false on failure.

# trader_ht_sine

(PECL trader >= 0.2.0)

trader_ht_sine — Hilbert Transform - SineWave

### 説明

function trader_ht_sine(array `$real`): array

### パラメータ

`real`

  実数値の配列。

### 戻り値

Returns an array with calculated data or false on failure.

# trader_ht_trendline

(PECL trader >= 0.2.0)

trader_ht_trendline — Hilbert Transform - Instantaneous Trendline

### 説明

function trader_ht_trendline(array `$real`): array

### パラメータ

`real`

  実数値の配列。

### 戻り値

Returns an array with calculated data or false on failure.

# trader_ht_trendmode

(PECL trader >= 0.2.0)

trader_ht_trendmode — Hilbert Transform - Trend vs Cycle Mode

### 説明

function trader_ht_trendmode(array `$real`): array

### パラメータ

`real`

  実数値の配列。

### 戻り値

Returns an array with calculated data or false on failure.

# trader_kama

(PECL trader >= 0.2.0)

trader_kama — Kaufman Adaptive Moving Average

### 説明

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

# trader_linearreg

(PECL trader >= 0.2.0)

trader_linearreg — Linear Regression

### 説明

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

# trader_linearreg_angle

(PECL trader >= 0.2.0)

trader_linearreg_angle — Linear Regression Angle

### 説明

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

# trader_linearreg_intercept

(PECL trader >= 0.2.0)

trader_linearreg_intercept — Linear Regression Intercept

### 説明

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

# trader_linearreg_slope

(PECL trader >= 0.2.0)

trader_linearreg_slope — Linear Regression Slope

### 説明

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

# trader_ln

(PECL trader >= 0.2.0)

trader_ln — Vector Log Natural

### 説明

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

# trader_log10

(PECL trader >= 0.2.0)

trader_log10 — Vector Log10

### 説明

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

# trader_ma

(PECL trader >= 0.2.0)

trader_ma — Moving average

### 説明

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

# trader_macd

(PECL trader >= 0.2.0)

trader_macd — Moving Average Convergence/Divergence

### 説明

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

# trader_macdext

(PECL trader >= 0.2.0)

trader_macdext — MACD with controllable MA type

### 説明

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

# trader_macdfix

(PECL trader >= 0.2.0)

trader_macdfix — Moving Average Convergence/Divergence Fix 12/26

### 説明

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

# trader_mama

(PECL trader >= 0.2.0)

trader_mama — MESA Adaptive Moving Average

### 説明

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

# trader_mavp

(PECL trader >= 0.2.0)

trader_mavp — Moving average with variable period

### 説明

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

# trader_max

(PECL trader >= 0.2.0)

trader_max — Highest value over a specified period

### 説明

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

# trader_maxindex

(PECL trader >= 0.2.0)

trader_maxindex — Index of highest value over a specified period

### 説明

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

# trader_medprice

(PECL trader >= 0.2.0)

trader_medprice — Median Price

### 説明

function trader_medprice(array `$high`, array `$low`): array

### パラメータ

`high`

  高値。実数値の配列。

`low`

  安値。実数値の配列。

### 戻り値

Returns an array with calculated data or false on failure.

# trader_mfi

(PECL trader >= 0.2.0)

trader_mfi — Money Flow Index

### 説明

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

# trader_midpoint

(PECL trader >= 0.2.0)

trader_midpoint — MidPoint over period

### 説明

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

# trader_midprice

(PECL trader >= 0.2.0)

trader_midprice — Midpoint Price over period

### 説明

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

# trader_min

(PECL trader >= 0.2.0)

trader_min — Lowest value over a specified period

### 説明

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

# trader_minindex

(PECL trader >= 0.2.0)

trader_minindex — Index of lowest value over a specified period

### 説明

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

# trader_minmax

(PECL trader >= 0.2.0)

trader_minmax — Lowest and highest values over a specified period

### 説明

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

# trader_minmaxindex

(PECL trader >= 0.2.0)

trader_minmaxindex — Indexes of lowest and highest values over a specified period

### 説明

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

# trader_minus_di

(PECL trader >= 0.2.0)

trader_minus_di — Minus Directional Indicator

### 説明

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

# trader_minus_dm

(PECL trader >= 0.2.0)

trader_minus_dm — Minus Directional Movement

### 説明

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

# trader_mom

(PECL trader >= 0.2.0)

trader_mom — Momentum

### 説明

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

# trader_mult

(PECL trader >= 0.2.0)

trader_mult — Vector Arithmetic Mult

### 説明

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

# trader_natr

(PECL trader >= 0.2.0)

trader_natr — Normalized Average True Range

### 説明

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

# trader_obv

(PECL trader >= 0.2.0)

trader_obv — On Balance Volume

### 説明

function trader_obv(array `$real`, array `$volume`): array

### パラメータ

`real`

  実数値の配列。

`volume`

  取引高。実数値の配列。

### 戻り値

Returns an array with calculated data or false on failure.

# trader_plus_di

(PECL trader >= 0.2.0)

trader_plus_di — Plus Directional Indicator

### 説明

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

# trader_plus_dm

(PECL trader >= 0.2.0)

trader_plus_dm — Plus Directional Movement

### 説明

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

# trader_ppo

(PECL trader >= 0.2.0)

trader_ppo — Percentage Price Oscillator

### 説明

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

# trader_roc

(PECL trader >= 0.2.0)

trader_roc — Rate of change : ((price/prevPrice)-1)*100

### 説明

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

# trader_rocp

(PECL trader >= 0.2.0)

trader_rocp — Rate of change Percentage: (price-prevPrice)/prevPrice

### 説明

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

# trader_rocr

(PECL trader >= 0.2.0)

trader_rocr — Rate of change ratio: (price/prevPrice)

### 説明

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

# trader_rocr100

(PECL trader >= 0.2.0)

trader_rocr100 — Rate of change ratio 100 scale: (price/prevPrice)*100

### 説明

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

# trader_rsi

(PECL trader >= 0.2.0)

trader_rsi — Relative Strength Index

### 説明

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

# trader_sar

(PECL trader >= 0.2.0)

trader_sar — Parabolic SAR

### 説明

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

# trader_sarext

(PECL trader >= 0.2.0)

trader_sarext — Parabolic SAR - Extended

### 説明

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

# trader_set_compat

(PECL trader >= 0.2.2)

trader_set_compat — Set compatibility mode

### 説明

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

### 戻り値

値を返しません。

# trader_set_unstable_period

(PECL trader >= 0.2.2)

trader_set_unstable_period — Set unstable period

### 説明

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

### 戻り値

値を返しません。

# trader_sin

(PECL trader >= 0.2.0)

trader_sin — Vector Trigonometric Sin

### 説明

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

# trader_sinh

(PECL trader >= 0.2.0)

trader_sinh — Vector Trigonometric Sinh

### 説明

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

# trader_sma

(PECL trader >= 0.2.0)

trader_sma — Simple Moving Average

### 説明

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

# trader_sqrt

(PECL trader >= 0.2.0)

trader_sqrt — Vector Square Root

### 説明

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

# trader_stddev

(PECL trader >= 0.2.0)

trader_stddev — Standard Deviation

### 説明

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

# trader_stoch

(PECL trader >= 0.2.0)

trader_stoch — Stochastic

### 説明

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

# trader_stochf

(PECL trader >= 0.2.0)

trader_stochf — Stochastic Fast

### 説明

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

# trader_stochrsi

(PECL trader >= 0.2.0)

trader_stochrsi — Stochastic Relative Strength Index

### 説明

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

# trader_sub

(PECL trader >= 0.2.0)

trader_sub — Vector Arithmetic Subtraction

### 説明

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

# trader_sum

(PECL trader >= 0.2.0)

trader_sum — Summation

### 説明

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

# trader_t3

(PECL trader >= 0.2.0)

trader_t3 — Triple Exponential Moving Average (T3)

### 説明

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

# trader_tan

(PECL trader >= 0.2.0)

trader_tan — Vector Trigonometric Tan

### 説明

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

# trader_tanh

(PECL trader >= 0.2.0)

trader_tanh — Vector Trigonometric Tanh

### 説明

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

# trader_tema

(PECL trader >= 0.2.0)

trader_tema — Triple Exponential Moving Average

### 説明

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

# trader_trange

(PECL trader >= 0.2.0)

trader_trange — True Range

### 説明

function trader_trange(array `$high`, array `$low`, array `$close`): array

### パラメータ

`high`

  高値。実数値の配列。

`low`

  安値。実数値の配列。

`close`

  終値。実数値の配列。

### 戻り値

Returns an array with calculated data or false on failure.

# trader_trima

(PECL trader >= 0.2.0)

trader_trima — Triangular Moving Average

### 説明

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

# trader_trix

(PECL trader >= 0.2.0)

trader_trix — 1-day Rate-Of-Change (ROC) of a Triple Smooth EMA

### 説明

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

# trader_tsf

(PECL trader >= 0.2.0)

trader_tsf — Time Series Forecast

### 説明

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

# trader_typprice

(PECL trader >= 0.2.0)

trader_typprice — Typical Price

### 説明

function trader_typprice(array `$high`, array `$low`, array `$close`): array

### パラメータ

`high`

  高値。実数値の配列。

`low`

  安値。実数値の配列。

`close`

  終値。実数値の配列。

### 戻り値

Returns an array with calculated data or false on failure.

# trader_ultosc

(PECL trader >= 0.2.0)

trader_ultosc — Ultimate Oscillator

### 説明

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

# trader_var

(PECL trader >= 0.2.0)

trader_var — Variance

### 説明

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

# trader_wclprice

(PECL trader >= 0.2.0)

trader_wclprice — Weighted Close Price

### 説明

function trader_wclprice(array `$high`, array `$low`, array `$close`): array

### パラメータ

`high`

  高値。実数値の配列。

`low`

  安値。実数値の配列。

`close`

  終値。実数値の配列。

### 戻り値

Returns an array with calculated data or false on failure.

# trader_willr

(PECL trader >= 0.2.0)

trader_willr — Williams' %R

### 説明

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

# trader_wma

(PECL trader >= 0.2.0)

trader_wma — Weighted Moving Average

### 説明

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

## 目次

- 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
[file cut: first 33554432 bytes kept]
